@xylex-group/athena 2.12.1 → 2.14.0

package/dist/cli/index.cjs

@@ -2004,7 +2004,7 @@ var getSessionCookie = (request2, config) => {
 
 // src/utils/athena-request-headers.ts
 var NO_CACHE_HEADER_VALUE = "no-cache";
-var API_KEY_HEADER_CANDIDATES = ["X-Api-Key", "x-api-key", "apikey"];
+var API_KEY_HEADER_CANDIDATES = ["X-Athena-Key", "x-athena-key", "X-Api-Key", "x-api-key", "apikey"];
 var ATHENA_KEY_HEADER_CANDIDATES = ["X-Athena-Key", "x-athena-key"];
 var SESSION_TOKEN_HEADER_CANDIDATES = ["X-Athena-Auth-Session-Token"];
 var BEARER_MIRROR_HEADER_CANDIDATES = ["X-Athena-Auth-Bearer-Token"];
@@ -2106,17 +2106,6 @@ function buildServiceRequestHeaders(profile, sdkHeaderValue, config, options, ex
   });
 }
 function applyAthenaApiKeyHeaders(headers, apiKey, athenaKey) {
-  if (apiKey) {
-    if (!hasHeaderIgnoreCase(headers, "apikey")) {
-      headers.apikey = apiKey;
-    }
-    if (!Object.hasOwn(headers, "x-api-key")) {
-      headers["x-api-key"] = apiKey;
-    }
-    if (!Object.hasOwn(headers, "X-Api-Key")) {
-      headers["X-Api-Key"] = apiKey;
-    }
-  }
   const resolvedAthenaKey = normalizeHeaderValue(athenaKey) ?? normalizeHeaderValue(apiKey);
   if (resolvedAthenaKey && !hasHeaderIgnoreCase(headers, "X-Athena-Key")) {
     headers["X-Athena-Key"] = resolvedAthenaKey;
@@ -2242,7 +2231,7 @@ function buildAthenaRequestHeaders(input) {
 
 // package.json
 var package_default = {
-  version: "2.12.1"
+  version: "2.14.0"
 };
 
 // src/sdk-version.ts
@@ -4335,39 +4324,224 @@ function createAuthClient(config = {}) {
   };
 }
 
-// src/db/module.ts
-function createDbModule(input) {
-  const db = {
-    from: input.from,
-    select(table, first, second) {
-      if (first && typeof first === "object" && !Array.isArray(first)) {
-        return input.from(table).select(void 0, first);
+// src/storage/direct-upload.ts
+var SERVICE = "s3";
+var TERMINATOR = "aws4_request";
+async function putDirectStorageUploadBody(config, bucket, storageKey, body, uploadHeaders, signal, onProgress) {
+  if (config.bucket && bucket && config.bucket !== bucket) {
+    throw new Error(
+      `athena.storage.file.upload direct mode bucket mismatch: configured ${config.bucket} but Athena returned ${bucket}`
+    );
+  }
+  const target = createDirectUploadTarget(config, bucket, storageKey);
+  const bytes = await bodyToArrayBuffer(body);
+  const payloadHash = await sha256Hex(bytes);
+  const headers = new Headers(uploadHeaders);
+  if (isBlobBody(body) && body.type && !headers.has("Content-Type")) {
+    headers.set("Content-Type", body.type);
+  }
+  const signed = await signDirectUploadRequest(config, target, headers, payloadHash);
+  if (typeof XMLHttpRequest !== "undefined") {
+    return putWithXhr(target.toString(), signed, body, signal, onProgress);
+  }
+  onProgress({ loaded: 0 });
+  const response = await fetch(target, {
+    method: "PUT",
+    headers: signed.requestHeaders,
+    body,
+    signal
+  });
+  if (!response.ok) {
+    throw new Error(`athena.storage.file.upload failed with status ${response.status}`);
+  }
+  onProgress({ loaded: bytes.byteLength });
+  return response;
+}
+function createDirectUploadTarget(config, bucket, storageKey) {
+  const resolvedBucket = config.bucket ?? bucket;
+  if (!resolvedBucket?.trim()) {
+    throw new Error(
+      "athena.storage.file.upload direct mode requires a bucket in experimental.directStorageUpload or the server upload response"
+    );
+  }
+  if (!storageKey.trim()) {
+    throw new Error("athena.storage.file.upload direct mode requires a storage key");
+  }
+  let endpoint;
+  try {
+    endpoint = new URL(config.endpoint);
+  } catch (error) {
+    throw new Error(
+      `athena.storage.file.upload direct mode received an invalid endpoint: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (endpoint.search || endpoint.hash) {
+    throw new Error("athena.storage.file.upload direct mode endpoint must not contain a query or hash");
+  }
+  const endpointPath = endpoint.pathname.replace(/\/+$/, "");
+  const pathParts = config.forcePathStyle === false ? [endpointPath, storageKey] : [endpointPath, resolvedBucket, storageKey];
+  if (config.forcePathStyle === false) {
+    endpoint.hostname = `${resolvedBucket}.${endpoint.hostname}`;
+  }
+  endpoint.pathname = pathParts.filter(Boolean).flatMap((part) => part.split("/")).map(awsEncode).join("/").replace(/^([^/])/, "/$1");
+  return endpoint;
+}
+async function signDirectUploadRequest(config, target, inputHeaders, payloadHash) {
+  const accessKeyId = config.accessKeyId.trim();
+  const secretAccessKey = config.secretAccessKey.trim();
+  if (!accessKeyId || !secretAccessKey) {
+    throw new Error(
+      "athena.storage.file.upload direct mode requires accessKeyId and secretAccessKey"
+    );
+  }
+  const now = /* @__PURE__ */ new Date();
+  const amzDate = formatAmzDate(now);
+  const shortDate = amzDate.slice(0, 8);
+  const region = config.region?.trim() || "auto";
+  const headers = {};
+  inputHeaders.forEach((value, key) => {
+    if (key.toLowerCase() !== "authorization" && key.toLowerCase() !== "host") {
+      headers[key.toLowerCase()] = value.trim().replace(/\s+/g, " ");
+    }
+  });
+  headers["x-amz-content-sha256"] = payloadHash;
+  headers["x-amz-date"] = amzDate;
+  if (config.sessionToken?.trim()) {
+    headers["x-amz-security-token"] = config.sessionToken.trim();
+  }
+  const canonicalHeaders = Object.keys(headers).sort().map((key) => `${key}:${headers[key]}
+`).join("");
+  const signedHeaders = Object.keys(headers).sort().join(";");
+  const canonicalRequest = [
+    "PUT",
+    target.pathname,
+    "",
+    `host:${target.host}
+${canonicalHeaders}`,
+    `host;${signedHeaders}`,
+    payloadHash
+  ].join("\n");
+  const credentialScope = `${shortDate}/${region}/${SERVICE}/${TERMINATOR}`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    credentialScope,
+    await sha256Hex(canonicalRequest)
+  ].join("\n");
+  const dateKey = await hmac(`AWS4${secretAccessKey}`, shortDate);
+  const regionKey = await hmac(dateKey, region);
+  const serviceKey = await hmac(regionKey, SERVICE);
+  const signingKey = await hmac(serviceKey, TERMINATOR);
+  const signature = await hmacHex(signingKey, stringToSign);
+  headers.authorization = `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${credentialScope}, SignedHeaders=host;${signedHeaders}, Signature=${signature}`;
+  return { requestHeaders: headers };
+}
+async function putWithXhr(url, signed, body, signal, onProgress) {
+  const Xhr = XMLHttpRequest;
+  if (Xhr === void 0) {
+    return Promise.reject(new Error("athena.storage.file.upload direct mode requires XMLHttpRequest in this runtime"));
+  }
+  return new Promise((resolve3, reject) => {
+    const xhr = new Xhr();
+    const abort = () => xhr.abort();
+    xhr.open("PUT", url);
+    Object.entries(signed.requestHeaders).forEach(([key, value]) => xhr.setRequestHeader(key, value));
+    xhr.upload.onprogress = (event) => onProgress({ loaded: event.loaded });
+    xhr.onload = () => {
+      signal?.removeEventListener("abort", abort);
+      if (xhr.status < 200 || xhr.status >= 300) {
+        reject(new Error(`athena.storage.file.upload failed with status ${xhr.status}`));
+        return;
       }
-      return input.from(table).select(first, second);
-    },
-    insert(table, values, options) {
-      return Array.isArray(values) ? input.from(table).insert(values, options) : input.from(table).insert(values, options);
-    },
-    upsert(table, values, options) {
-      return Array.isArray(values) ? input.from(table).upsert(values, options) : input.from(table).upsert(values, options);
-    },
-    update(table, values, options) {
-      return input.from(table).update(values, options);
-    },
-    delete(table, options) {
-      return input.from(table).delete(options);
-    },
-    rpc(fn, args, options) {
-      return input.rpc(fn, args, options);
-    },
-    query(query, options) {
-      return input.query(query, options);
+      onProgress({ loaded: bodySize(body) });
+      resolve3(new Response(xhr.response, {
+        status: xhr.status,
+        statusText: xhr.statusText,
+        headers: parseXhrHeaders(xhr.getAllResponseHeaders())
+      }));
+    };
+    xhr.onerror = () => {
+      signal?.removeEventListener("abort", abort);
+      reject(new Error("athena.storage.file.upload failed with a network error"));
+    };
+    xhr.onabort = () => {
+      signal?.removeEventListener("abort", abort);
+      reject(new DOMException("Upload aborted", "AbortError"));
+    };
+    if (signal) {
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      signal.addEventListener("abort", abort, { once: true });
     }
-  };
-  return db;
+    xhr.send(body);
+  });
+}
+function isBlobBody(body) {
+  return typeof Blob !== "undefined" && body instanceof Blob;
+}
+async function bodyToArrayBuffer(body) {
+  if (isBlobBody(body)) return body.arrayBuffer();
+  if (body instanceof ArrayBuffer) return body;
+  if (ArrayBuffer.isView(body)) {
+    return body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+  }
+  throw new Error("athena.storage.file.upload direct mode does not support ReadableStream bodies");
+}
+function bodySize(body) {
+  if (isBlobBody(body)) return body.size;
+  if (body instanceof ArrayBuffer) return body.byteLength;
+  if (ArrayBuffer.isView(body)) return body.byteLength;
+  return 0;
+}
+function awsEncode(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function formatAmzDate(date) {
+  return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
+}
+async function sha256Hex(value) {
+  const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value;
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return toHex(new Uint8Array(digest));
+}
+async function hmac(key, value) {
+  const keyBytes = typeof key === "string" ? new TextEncoder().encode(key) : key;
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyBytes,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  return crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(value));
+}
+async function hmacHex(key, value) {
+  return toHex(new Uint8Array(await hmac(key, value)));
+}
+function toHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function parseXhrHeaders(rawHeaders) {
+  const headers = new Headers();
+  rawHeaders.trim().split(/[\r\n]+/).forEach((line) => {
+    const separator = line.indexOf(":");
+    if (separator > 0) {
+      headers.set(line.slice(0, separator).trim(), line.slice(separator + 1).trim());
+    }
+  });
+  return headers;
 }
 
 // src/storage/file.ts
+function mergeUploadHeaders(serverHeaders, inputHeaders) {
+  const headers = { ...serverHeaders };
+  new Headers(inputHeaders).forEach((value, key) => {
+    headers[key] = value;
+  });
+  return headers;
+}
 function createStorageFileModule(base, config = {}) {
   const upload = async (input, options) => {
     const sources = normalizeUploadSources(input);
@@ -4403,16 +4577,25 @@ function createStorageFileModule(base, config = {}) {
     for (let index = 0; index < uploadRequests.length; index += 1) {
       const request2 = uploadRequests[index];
       const uploadUrl = uploadUrls[index];
-      const response = await putUploadBody(
+      const aggregateProgress = (progress) => {
+        aggregateLoaded[index] = progress.loaded;
+        input.onProgress?.(createProgressSnapshot("uploading", sources, index, progress.loaded, sum(aggregateLoaded)));
+      };
+      const response = config.directUpload ? await putDirectStorageUploadBody(
+        config.directUpload,
+        uploadUrl.upload.bucket,
+        uploadUrl.upload.storage_key,
+        request2.source.source,
+        mergeUploadHeaders(uploadUrl.upload.headers ?? {}, input.uploadHeaders),
+        options?.signal,
+        aggregateProgress
+      ) : await putUploadBody(
         uploadUrl.upload.url,
         uploadUrl.upload.headers ?? {},
         request2.source,
         input,
         options,
-        (progress) => {
-          aggregateLoaded[index] = progress.loaded;
-          input.onProgress?.(createProgressSnapshot("uploading", sources, index, progress.loaded, sum(aggregateLoaded)));
-        }
+        aggregateProgress
       );
       uploaded.push({
         file: uploadUrl.file,
@@ -4563,7 +4746,7 @@ function putUploadBodyWithXhr(url, source, headers, options, onProgress) {
       resolve3(new Response(xhr.response, {
         status: xhr.status,
         statusText: xhr.statusText,
-        headers: parseXhrHeaders(xhr.getAllResponseHeaders())
+        headers: parseXhrHeaders2(xhr.getAllResponseHeaders())
       }));
     };
     xhr.onerror = () => {
@@ -4701,7 +4884,7 @@ function createProgressSnapshot(phase, sources, fileIndex, loaded, aggregateLoad
 function sum(values) {
   return values.reduce((total, value) => total + value, 0);
 }
-function parseXhrHeaders(raw) {
+function parseXhrHeaders2(raw) {
   const headers = new Headers();
   for (const line of raw.trim().split(/[\r\n]+/)) {
     const index = line.indexOf(":");
@@ -4718,6 +4901,230 @@ function isRecord5(value) {
   return Boolean(value) && typeof value === "object";
 }
 
+// src/storage/backup.ts
+function backupError(message, status, endpoint, method, cause, raw) {
+  const error = new Error(message);
+  error.name = "AthenaStorageError";
+  error.code = status === 0 ? "NETWORK_ERROR" : "HTTP_ERROR";
+  error.status = status;
+  error.endpoint = endpoint;
+  error.method = method;
+  error.cause = cause;
+  error.raw = raw;
+  throw error;
+}
+function isRecord6(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function asPath(path) {
+  return path;
+}
+function appendQuery(path, query) {
+  if (!query) return path;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null || value === "") continue;
+    params.set(key, String(value));
+  }
+  const text = params.toString();
+  return text ? `${path}?${text}` : path;
+}
+function unwrapAthenaData(payload) {
+  if (isRecord6(payload) && "data" in payload) {
+    return payload.data;
+  }
+  return payload;
+}
+function requireKey(key) {
+  const trimmed = key.trim();
+  if (!trimmed || trimmed === "undefined" || trimmed === "null") {
+    backupError("Backup object key is required", 400, "/admin/backups/{key}", "DELETE");
+  }
+  return trimmed;
+}
+function resolveMessage(payload, fallback) {
+  if (isRecord6(payload)) {
+    const message = payload.message ?? payload.error ?? payload.details;
+    if (typeof message === "string" && message.trim()) return message.trim();
+  }
+  if (typeof payload === "string" && payload.trim()) return payload.trim();
+  return fallback;
+}
+async function callBackupEndpoint(gateway, path, method, payload, options, runtime) {
+  const endpoint = asPath(path);
+  const baseUrl = options?.baseUrl ? normalizeAthenaGatewayBaseUrl(options.baseUrl) : gateway.baseUrl;
+  const url = buildAthenaGatewayUrl(baseUrl, endpoint);
+  const headers = gateway.buildHeaders(options);
+  const init = {
+    method,
+    headers,
+    signal: options?.signal
+  };
+  if (payload !== void 0 && method !== "GET") {
+    init.body = JSON.stringify(payload);
+  }
+  let response;
+  try {
+    response = await fetch(url, init);
+  } catch (error) {
+    backupError(
+      error instanceof Error ? error.message : "Backup network error",
+      0,
+      path,
+      method,
+      error
+    );
+  }
+  const rawText = await response.text();
+  let parsed = null;
+  if (rawText) {
+    try {
+      parsed = JSON.parse(rawText);
+    } catch {
+      parsed = rawText;
+    }
+  }
+  if (!response.ok) {
+    backupError(
+      resolveMessage(parsed, `Backup ${method} ${path} failed (${response.status})`),
+      response.status,
+      path,
+      method,
+      void 0,
+      parsed
+    );
+  }
+  return unwrapAthenaData(parsed);
+}
+function createStorageBackupModule(gateway, runtimeOptions) {
+  const resolvedBaseUrl = () => String(gateway.baseUrl ?? "").replace(/\/+$/, "");
+  return {
+    async list(query, options) {
+      const path = appendQuery("/admin/backups", {
+        limit: query?.limit ?? 10,
+        client_name: query?.client_name,
+        cursor: query?.cursor ?? void 0
+      });
+      const data = await callBackupEndpoint(gateway, path, "GET", void 0, options);
+      const backups = (data?.backups ?? []).map((row) => ({
+        ...row,
+        key: row.key ?? row.s3_key
+      }));
+      return {
+        backups,
+        next_cursor: data?.next_cursor ?? null
+      };
+    },
+    async create(input, options) {
+      const data = await callBackupEndpoint(gateway, "/admin/backups", "POST", input, options);
+      return {
+        job_id: Number(data?.job_id ?? 0),
+        client_name: String(data?.client_name ?? input.client_name),
+        status: String(data?.status ?? "pending")
+      };
+    },
+    async restore(key, input, options) {
+      const backupKey = requireKey(key);
+      const path = `/admin/backups/${encodeURIComponent(backupKey)}/restore`;
+      const data = await callBackupEndpoint(gateway, path, "POST", input, options);
+      return {
+        job_id: Number(data?.job_id ?? 0),
+        client_name: String(data?.client_name ?? input.client_name),
+        status: String(data?.status ?? "pending"),
+        key: String(data?.key ?? backupKey)
+      };
+    },
+    async delete(key, options) {
+      const backupKey = requireKey(key);
+      await callBackupEndpoint(
+        gateway,
+        `/admin/backups/${encodeURIComponent(backupKey)}`,
+        "DELETE",
+        void 0,
+        options);
+    },
+    downloadUrl(key, options) {
+      const backupKey = requireKey(key);
+      const base = `${resolvedBaseUrl()}/admin/backups/${encodeURIComponent(backupKey)}/download`;
+      return options?.apiKey ? `${base}?api_key=${encodeURIComponent(options.apiKey)}` : base;
+    },
+    jobs: {
+      async list(query, options) {
+        const path = appendQuery("/admin/backups/jobs", query ?? {});
+        const data = await callBackupEndpoint(gateway, path, "GET", void 0, options);
+        if (Array.isArray(data)) return data;
+        if (isRecord6(data) && Array.isArray(data.jobs)) return data.jobs;
+        return [];
+      },
+      async get(jobId, options) {
+        return callBackupEndpoint(
+          gateway,
+          `/admin/backups/jobs/${encodeURIComponent(String(jobId))}`,
+          "GET",
+          void 0,
+          options);
+      },
+      async cancel(jobId, options) {
+        return callBackupEndpoint(
+          gateway,
+          `/admin/backups/jobs/${encodeURIComponent(String(jobId))}/cancel`,
+          "POST",
+          {},
+          options);
+      },
+      async delete(jobId, options) {
+        await callBackupEndpoint(
+          gateway,
+          `/admin/backups/jobs/${encodeURIComponent(String(jobId))}`,
+          "DELETE",
+          void 0,
+          options);
+      },
+      async openObjectUrl(jobId, options) {
+        const data = await callBackupEndpoint(
+          gateway,
+          `/admin/backups/jobs/${encodeURIComponent(String(jobId))}/s3-open`,
+          "GET",
+          void 0,
+          options);
+        return String(data?.url ?? "");
+      }
+    },
+    schedules: {
+      async list(options) {
+        const data = await callBackupEndpoint(gateway, "/admin/backups/schedules", "GET", void 0, options);
+        if (Array.isArray(data)) return data;
+        if (isRecord6(data) && Array.isArray(data.schedules)) return data.schedules;
+        return [];
+      },
+      async create(input, options) {
+        return callBackupEndpoint(
+          gateway,
+          "/admin/backups/schedules",
+          "POST",
+          input,
+          options);
+      },
+      async update(id, input, options) {
+        return callBackupEndpoint(
+          gateway,
+          `/admin/backups/schedules/${encodeURIComponent(String(id))}`,
+          "PATCH",
+          input,
+          options);
+      },
+      async delete(id, options) {
+        await callBackupEndpoint(
+          gateway,
+          `/admin/backups/schedules/${encodeURIComponent(String(id))}`,
+          "DELETE",
+          void 0,
+          options);
+      }
+    }
+  };
+}
+
 // src/storage/module.ts
 var storageSdkManifest = {
   methods: [
@@ -4760,6 +5167,53 @@ var storageSdkManifest = {
       responseEnvelope: "raw",
       responseType: "{ data: S3CredentialListItem[] }"
     },
+    {
+      name: "backup.list",
+      method: "GET",
+      path: "/admin/backups",
+      responseEnvelope: "athena",
+      responseType: "StorageBackupListPage",
+      note: "Admin backup archives on server S3/R2 profile"
+    },
+    {
+      name: "backup.create",
+      method: "POST",
+      path: "/admin/backups",
+      requestType: "StorageBackupCreateRequest",
+      responseEnvelope: "athena",
+      responseType: "StorageBackupQueuedJob"
+    },
+    {
+      name: "backup.restore",
+      method: "POST",
+      path: "/admin/backups/{key}/restore",
+      pathParams: ["key"],
+      requestType: "StorageBackupRestoreRequest",
+      responseEnvelope: "athena",
+      responseType: "StorageBackupQueuedJob"
+    },
+    {
+      name: "backup.delete",
+      method: "DELETE",
+      path: "/admin/backups/{key}",
+      pathParams: ["key"],
+      responseEnvelope: "athena",
+      responseType: "void"
+    },
+    {
+      name: "backup.jobs.list",
+      method: "GET",
+      path: "/admin/backups/jobs",
+      responseEnvelope: "athena",
+      responseType: "StorageBackupJob[]"
+    },
+    {
+      name: "backup.schedules.list",
+      method: "GET",
+      path: "/admin/backups/schedules",
+      responseEnvelope: "athena",
+      responseType: "StorageBackupSchedule[]"
+    },
     {
       name: "createStorageUploadUrl",
       method: "POST",
@@ -5407,7 +5861,7 @@ var AthenaStorageError = class extends Error {
     };
   }
 };
-function isRecord6(value) {
+function isRecord7(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function causeToString(cause) {
@@ -5505,7 +5959,7 @@ function parseResponseBody3(rawText, contentType) {
     return { parsed: rawText, parseFailed: true };
   }
 }
-function appendQuery(path, query) {
+function appendQuery2(path, query) {
   if (!query) return path;
   const params = new URLSearchParams();
   for (const [key, value] of Object.entries(query)) {
@@ -5531,7 +5985,7 @@ function withPathParam(path, name, value) {
   return path.replace(`{${name}}`, encodeURIComponent(value));
 }
 function resolveErrorMessage3(payload, fallback) {
-  if (isRecord6(payload)) {
+  if (isRecord7(payload)) {
     const message = payload.message ?? payload.error ?? payload.details;
     if (typeof message === "string" && message.trim()) {
       return message.trim();
@@ -5543,12 +5997,12 @@ function resolveErrorMessage3(payload, fallback) {
   return fallback;
 }
 function resolveErrorHint2(payload) {
-  if (!isRecord6(payload)) return void 0;
+  if (!isRecord7(payload)) return void 0;
   const hint = payload.hint ?? payload.suggestion;
   return typeof hint === "string" && hint.trim() ? hint.trim() : void 0;
 }
 function resolveErrorCause(payload) {
-  if (!isRecord6(payload)) return void 0;
+  if (!isRecord7(payload)) return void 0;
   const cause = payload.cause ?? payload.reason;
   return typeof cause === "string" && cause.trim() ? cause.trim() : void 0;
 }
@@ -5667,7 +6121,7 @@ async function callStorageEndpoint(gateway, endpoint, method, envelope, payload,
     );
   }
   if (envelope === "athena") {
-    if (!isRecord6(parsedBody.parsed) || !("data" in parsedBody.parsed)) {
+    if (!isRecord7(parsedBody.parsed) || !("data" in parsedBody.parsed)) {
       return rejectStorageError(
         {
           code: "INVALID_ATHENA_ENVELOPE",
@@ -5775,7 +6229,7 @@ async function callStorageBinaryEndpoint(gateway, endpoint, method, options, run
     runtimeOptions
   );
 }
-function isBlobBody(body) {
+function isBlobBody2(body) {
   return typeof Blob !== "undefined" && body instanceof Blob;
 }
 function isReadableStreamBody(body) {
@@ -5784,7 +6238,7 @@ function isReadableStreamBody(body) {
 async function putPresignedUploadBody(uploadUrl, uploadHeaders, body, options) {
   const headers = new Headers(uploadHeaders);
   Object.entries(options?.headers ?? {}).forEach(([key, value]) => headers.set(key, value));
-  if (!headers.has("Content-Type") && isBlobBody(body) && body.type) {
+  if (!headers.has("Content-Type") && isBlobBody2(body) && body.type) {
     headers.set("Content-Type", body.type);
   }
   const init = {
@@ -5879,7 +6333,7 @@ async function callStorageUploadBinaryEndpoint(gateway, endpoint, body, options,
   }
   delete headers["Content-Type"];
   delete headers["content-type"];
-  if (isBlobBody(body) && body.type) {
+  if (isBlobBody2(body) && body.type) {
     headers["Content-Type"] = body.type;
   }
   const requestInit = {
@@ -5964,7 +6418,7 @@ async function callStorageUploadBinaryEndpoint(gateway, endpoint, body, options,
       runtimeOptions
     );
   }
-  if (!isRecord6(parsedBody.parsed) || !("data" in parsedBody.parsed)) {
+  if (!isRecord7(parsedBody.parsed) || !("data" in parsedBody.parsed)) {
     return rejectStorageError(
       {
         code: "INVALID_ATHENA_ENVELOPE",
@@ -6036,14 +6490,14 @@ function createStorageModule(gateway, runtimeOptions) {
       return callAthena2(withPathParam("/storage/files/{file_id}", "file_id", fileId), "GET", void 0, options);
     },
     getStorageFileUrl(fileId, query, options) {
-      const path = appendQuery(
+      const path = appendQuery2(
         withPathParam("/storage/files/{file_id}/url", "file_id", fileId),
         query
       );
       return callAthena2(path, "GET", void 0, options);
     },
     getStorageFileProxy(fileId, query, options) {
-      const path = appendQuery(
+      const path = appendQuery2(
         withPathParam("/storage/files/{file_id}/proxy", "file_id", fileId),
         query
       );
@@ -6067,7 +6521,7 @@ function createStorageModule(gateway, runtimeOptions) {
   };
   const fileFacade = createStorageFileModule(base, runtimeOptions);
   const fileUpload = ((input, options) => {
-    if (isRecord6(input) && "files" in input) {
+    if (isRecord7(input) && "files" in input) {
       return fileFacade.upload(input, options);
     }
     return base.createStorageUploadUrl(
@@ -6129,7 +6583,7 @@ function createStorageModule(gateway, runtimeOptions) {
       return callAthena2(withPathParam("/storage/files/{file_id}/public-url", "file_id", fileId), "GET", void 0, options);
     },
     proxyUrl(fileId, query, options) {
-      const path = appendQuery(
+      const path = appendQuery2(
         withPathParam("/storage/files/{file_id}/proxy-url", "file_id", fileId),
         query
       );
@@ -6167,7 +6621,7 @@ function createStorageModule(gateway, runtimeOptions) {
     },
     retention: {
       get(fileId, query, options) {
-        const path = appendQuery(
+        const path = appendQuery2(
           withPathParam("/storage/files/{file_id}/retention", "file_id", fileId),
           query
         );
@@ -6369,6 +6823,7 @@ function createStorageModule(gateway, runtimeOptions) {
       return callAthena2("/storage/audit/list", "POST", input, options);
     }
   };
+  const backup = createStorageBackupModule(gateway);
   return {
     ...base,
     credentials,
@@ -6380,6 +6835,7 @@ function createStorageModule(gateway, runtimeOptions) {
     bucket,
     multipart,
     audit,
+    backup,
     delete: file.delete
   };
 }
@@ -6429,7 +6885,7 @@ function normalizeWsUrl(value, label) {
   parsed.pathname = parsed.pathname.replace(/\/+$/, "");
   return parsed.toString().replace(/\/$/, "");
 }
-function isRecord7(value) {
+function isRecord8(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function parseResponseBody4(rawText, contentType) {
@@ -6451,7 +6907,7 @@ function resolveRequestId3(headers) {
   return headers.get("x-request-id") ?? headers.get("x-correlation-id") ?? headers.get("x-athena-request-id") ?? void 0;
 }
 function resolveErrorMessage4(payload, fallback) {
-  if (isRecord7(payload)) {
+  if (isRecord8(payload)) {
     for (const candidate of [payload.error, payload.message, payload.details]) {
       if (typeof candidate === "string" && candidate.trim().length > 0) {
         return candidate.trim();
@@ -6860,7 +7316,7 @@ var BOOLEAN_SAFE_OPERATORS = /* @__PURE__ */ new Set([
   "ilike",
   "is"
 ]);
-function isRecord8(value) {
+function isRecord9(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function isUuidString(value) {
@@ -6873,7 +7329,7 @@ function shouldUseUuidTextComparison(column, value) {
   return typeof value === "string" && isUuidString(value) && isUuidIdentifierColumn(column);
 }
 function isRelationSelectNode(value) {
-  return isRecord8(value) && isRecord8(value.select);
+  return isRecord9(value) && isRecord9(value.select);
 }
 function normalizeIdentifier(value, label) {
   const normalized = value.trim();
@@ -6929,7 +7385,7 @@ function compileRelationToken(key, node) {
   return `${prefix}${relationToken}(${nested})`;
 }
 function compileSelectShape(select) {
-  if (!isRecord8(select)) {
+  if (!isRecord9(select)) {
     throw new Error("findMany select must be an object");
   }
   const tokens = [];
@@ -6953,7 +7409,7 @@ function compileSelectShape(select) {
   return tokens.join(",");
 }
 function selectShapeUsesRelationSchema(select) {
-  if (!isRecord8(select)) {
+  if (!isRecord9(select)) {
     return false;
   }
   for (const rawValue of Object.values(select)) {
@@ -6971,7 +7427,7 @@ function selectShapeUsesRelationSchema(select) {
 }
 function compileColumnWhere(column, input) {
   const normalizedColumn = normalizeIdentifier(column, "where column");
-  if (!isRecord8(input)) {
+  if (!isRecord9(input)) {
     return [buildGatewayCondition("eq", normalizedColumn, input)];
   }
   const conditions = [];
@@ -6999,7 +7455,7 @@ function compileColumnWhere(column, input) {
   return conditions;
 }
 function compileBooleanExpressionTerms(clause, label) {
-  if (!isRecord8(clause)) {
+  if (!isRecord9(clause)) {
     throw new Error(`findMany where.${label} clauses must be objects`);
   }
   const entries = Object.entries(clause).filter(([, value]) => value !== void 0);
@@ -7008,7 +7464,7 @@ function compileBooleanExpressionTerms(clause, label) {
   }
   const [rawColumn, rawValue] = entries[0];
   const column = normalizeIdentifier(rawColumn, `where.${label} column`);
-  if (!isRecord8(rawValue)) {
+  if (!isRecord9(rawValue)) {
     return [`${column}.eq.${stringifyFilterValue(rawValue)}`];
   }
   const operatorEntries = Object.entries(rawValue).filter(([, value]) => value !== void 0);
@@ -7032,7 +7488,7 @@ function compileWhere(where) {
   if (where === void 0) {
     return void 0;
   }
-  if (!isRecord8(where)) {
+  if (!isRecord9(where)) {
     throw new Error("findMany where must be an object");
   }
   const conditions = [];
@@ -7082,7 +7538,7 @@ function compileOrderBy(orderBy) {
   if (orderBy === void 0) {
     return void 0;
   }
-  if (!isRecord8(orderBy)) {
+  if (!isRecord9(orderBy)) {
     throw new Error("findMany orderBy must be an object");
   }
   if ("column" in orderBy) {
@@ -7257,11 +7713,11 @@ function toFindManyAstOrder(order) {
     ascending: order.direction !== "descending"
   };
 }
-function isRecord9(value) {
+function isRecord10(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeFindManyAstColumnPredicate(value) {
-  if (!isRecord9(value)) {
+  if (!isRecord10(value)) {
     return {
       eq: value
     };
@@ -7285,7 +7741,7 @@ function normalizeFindManyAstBooleanOperand(clause) {
   return normalized;
 }
 function normalizeFindManyAstWhere(where) {
-  if (!where || !isRecord9(where)) {
+  if (!where || !isRecord10(where)) {
     return where;
   }
   const normalized = {};
@@ -7299,7 +7755,7 @@ function normalizeFindManyAstWhere(where) {
       );
       continue;
     }
-    if (key === "not" && isRecord9(value)) {
+    if (key === "not" && isRecord10(value)) {
       normalized.not = normalizeFindManyAstBooleanOperand(
         value
       );
@@ -7310,7 +7766,7 @@ function normalizeFindManyAstWhere(where) {
   return normalized;
 }
 function predicateRequiresUuidQueryFallback(column, value) {
-  if (!isRecord9(value)) {
+  if (!isRecord10(value)) {
     return shouldUseUuidTextComparison(column, value);
   }
   const eqValue = value.eq;
@@ -7328,7 +7784,7 @@ function booleanOperandRequiresUuidQueryFallback(clause) {
   return false;
 }
 function findManyAstWhereRequiresLegacyTransport(where) {
-  if (!where || !isRecord9(where)) {
+  if (!where || !isRecord10(where)) {
     return false;
   }
   for (const [key, value] of Object.entries(where)) {
@@ -7343,7 +7799,7 @@ function findManyAstWhereRequiresLegacyTransport(where) {
       }
       continue;
     }
-    if (key === "not" && isRecord9(value)) {
+    if (key === "not" && isRecord10(value)) {
       if (booleanOperandRequiresUuidQueryFallback(value)) {
         return true;
       }
@@ -7963,7 +8419,7 @@ async function executeExperimentalRead(experimental, runner) {
     throw error;
   }
 }
-function isRecord10(value) {
+function isRecord11(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function firstNonEmptyString2(...values) {
@@ -7975,8 +8431,8 @@ function firstNonEmptyString2(...values) {
   return void 0;
 }
 function resolveStructuredErrorPayload2(raw) {
-  if (!isRecord10(raw)) return null;
-  return isRecord10(raw.error) ? raw.error : raw;
+  if (!isRecord11(raw)) return null;
+  return isRecord11(raw.error) ? raw.error : raw;
 }
 function resolveStructuredErrorDetails(payload, message) {
   if (!payload || !("details" in payload)) {
@@ -7992,7 +8448,7 @@ function resolveStructuredErrorDetails(payload, message) {
   return details;
 }
 function createResultError(response, result, normalized) {
-  const rawRecord = isRecord10(response.raw) ? response.raw : null;
+  const rawRecord = isRecord11(response.raw) ? response.raw : null;
   const payload = resolveStructuredErrorPayload2(response.raw);
   const message = firstNonEmptyString2(
     response.error,
@@ -9714,7 +10170,30 @@ function createClientFromConfig(config, sourceConfig) {
     config.experimental,
     queryTracer
   );
-  const db = createDbModule({ from, rpc, query });
+  const untypedDbFrom = from;
+  const db = {
+    from,
+    select(table, first, second) {
+      if (first && typeof first === "object" && !Array.isArray(first)) {
+        return untypedDbFrom(table).select(void 0, first);
+      }
+      return untypedDbFrom(table).select(first, second);
+    },
+    insert(table, values, options) {
+      return Array.isArray(values) ? untypedDbFrom(table).insert(values, options) : untypedDbFrom(table).insert(values, options);
+    },
+    upsert(table, values, options) {
+      return Array.isArray(values) ? untypedDbFrom(table).upsert(values, options) : untypedDbFrom(table).upsert(values, options);
+    },
+    update(table, values, options) {
+      return untypedDbFrom(table).update(values, options);
+    },
+    delete(table, options) {
+      return untypedDbFrom(table).delete(options);
+    },
+    rpc,
+    query
+  };
   const chat = createChatModule({
     baseUrl: config.chatUrl,
     apiKey: config.apiKey,
@@ -9852,6 +10331,7 @@ function createClientFromConfig(config, sourceConfig) {
       withOptions: storageWithOptions,
       storage: createStorageModule(gateway, {
         ...config.experimental.storage,
+        ...config.experimental.directStorageUpload ? { directUpload: config.experimental.directStorageUpload } : {},
         ...config.storageUrl ? {
           baseUrl: config.storageUrl,
           stripBasePath: true
@@ -9862,7 +10342,8 @@ function createClientFromConfig(config, sourceConfig) {
   }
   return sdkClient;
 }
-function createClient(configOrUrl, apiKey, options) {
+function createClient(...args) {
+  const [configOrUrl, apiKey, options] = args;
   if (typeof configOrUrl === "string" || configOrUrl === null || configOrUrl === void 0) {
     return createClientFromInput({
       url: configOrUrl,
@@ -10469,6 +10950,10 @@ async function runSchemaGenerator(options = {}) {
 }
 
 // src/cli/index.ts
+function isDebugEnabled() {
+  const value = globalThis.process?.env?.ATHENA_JS_DEBUG;
+  return value === "1" || value === "true";
+}
 function rootUsage() {
   return [
     "athena-js CLI",
@@ -10632,7 +11117,61 @@ function extractMissingDatabaseName(message) {
 function isErrorWithCode(error) {
   return typeof error === "object" && error !== null && "code" in error;
 }
+function isNetworkConnectionError(error) {
+  if (!isErrorWithCode(error)) {
+    return false;
+  }
+  const code = typeof error.code === "string" ? error.code : "";
+  if (code === "ECONNRESET" || code === "ECONNREFUSED" || code === "ETIMEDOUT" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "EPIPE" || code === "EHOSTUNREACH" || code === "ENETUNREACH") {
+    return true;
+  }
+  const message = normalizeErrorMessage(error).toLowerCase();
+  return message.includes("econnreset") || message.includes("econnrefused") || message.includes("etimedout") || message.includes("connection terminated") || message.includes("connection refused") || message.includes("timeout expired");
+}
+function collectErrorDiagnostics(error) {
+  const lines = [];
+  if (!isErrorWithCode(error) && !(error instanceof Error)) {
+    return lines;
+  }
+  const code = isErrorWithCode(error) && error.code !== void 0 ? String(error.code) : void 0;
+  if (code) {
+    lines.push(`  code: ${code}`);
+  }
+  const errno = isErrorWithCode(error) && error.errno !== void 0 ? String(error.errno) : void 0;
+  if (errno) {
+    lines.push(`  errno: ${errno}`);
+  }
+  const syscall = isErrorWithCode(error) && typeof error.syscall === "string" ? error.syscall : void 0;
+  if (syscall) {
+    lines.push(`  syscall: ${syscall}`);
+  }
+  const address = isErrorWithCode(error) && typeof error.address === "string" ? error.address : void 0;
+  const port = isErrorWithCode(error) && error.port !== void 0 ? String(error.port) : void 0;
+  if (address || port) {
+    lines.push(
+      `  remote: ${address ?? "?"}${port ? `:${port}` : ""}`
+    );
+  }
+  const hostname = isErrorWithCode(error) && typeof error.hostname === "string" ? error.hostname : void 0;
+  if (hostname) {
+    lines.push(`  hostname: ${hostname}`);
+  }
+  let cause = error instanceof Error ? error.cause : isErrorWithCode(error) ? error.cause : void 0;
+  let depth = 0;
+  while (cause && depth < 4) {
+    const causeMessage = normalizeErrorMessage(cause);
+    const causeCode = isErrorWithCode(cause) && cause.code !== void 0 ? String(cause.code) : void 0;
+    lines.push(
+      `  cause[${depth}]: ${causeCode ? `${causeCode} \u2014 ` : ""}${causeMessage}`
+    );
+    cause = cause instanceof Error ? cause.cause : isErrorWithCode(cause) ? cause.cause : void 0;
+    depth += 1;
+  }
+  return lines;
+}
 function formatGeneratorError(error, configPath) {
+  const diagnostics = collectErrorDiagnostics(error);
+  const diagnosticsBlock = diagnostics.length > 0 ? ["", "Diagnostics:", ...diagnostics] : [];
   if (isErrorWithCode(error) && error.code === "3D000") {
     const message = normalizeErrorMessage(error);
     const databaseName = extractMissingDatabaseName(message);
@@ -10641,15 +11180,58 @@ function formatGeneratorError(error, configPath) {
     return new Error(
       [
         `${databaseLabel} (code 3D000).`,
-        `Update provider.connectionString (and provider.database, if set) in ${configLabel}, or create that database before running generate.`
+        `Update provider.connectionString (and provider.database, if set) in ${configLabel}, or create that database before running generate.`,
+        ...diagnosticsBlock,
+        "",
+        "Hint: ATHENA_JS_DEBUG=1 pnpm exec athena-js generate"
+      ].join("\n")
+    );
+  }
+  if (isNetworkConnectionError(error)) {
+    const message = normalizeErrorMessage(error);
+    const configLabel = configPath ? `config "${configPath}"` : "the resolved athena config";
+    const code = isErrorWithCode(error) && typeof error.code === "string" ? error.code : "network";
+    return new Error(
+      [
+        `Schema introspection failed: database connection was reset or unreachable (${code}: ${message}).`,
+        `The CLI started correctly; generate could not finish talking to Postgres for ${configLabel}.`,
+        ...diagnosticsBlock,
+        "",
+        "Check:",
+        "  1. DATABASE_URL / provider.connectionString is reachable from this machine (VPN, Railway proxy, firewall).",
+        '  2. The database is running and accepts connections (try `psql "$DATABASE_URL" -c "select 1"`).',
+        "  3. SSL settings match the host (Railway/public proxy often needs `?sslmode=require`).",
+        "  4. Retry once \u2014 ECONNRESET is often a transient proxy drop mid-introspection.",
+        "",
+        "For a full stack: ATHENA_JS_DEBUG=1 pnpm exec athena-js generate"
       ].join("\n")
     );
   }
   if (error instanceof Error) {
-    return error;
+    if (diagnostics.length === 0 && !isDebugEnabled()) {
+      return error;
+    }
+    const base = error.message || normalizeErrorMessage(error);
+    return new Error(
+      [
+        base,
+        ...diagnosticsBlock,
+        ...isDebugEnabled() && error.stack ? ["", "Stack:", error.stack] : ["", "Hint: ATHENA_JS_DEBUG=1 pnpm exec athena-js generate"]
+      ].join("\n")
+    );
   }
   return new Error(normalizeErrorMessage(error));
 }
+function logCliError(error, errorLog = console.error) {
+  const message = error instanceof Error ? error.message : normalizeErrorMessage(error);
+  errorLog(message);
+  if (isDebugEnabled() && error instanceof Error && error.stack) {
+    const stackOnly = error.stack.startsWith(error.message) ? error.stack.slice(error.message.length).replace(/^\n/, "") : error.stack;
+    if (stackOnly) {
+      errorLog(stackOnly);
+    }
+  }
+}
 function formatSkippedArtifactLine(artifact) {
   if (artifact.reason === "protected-existing-file") {
     return ` [skip] ${artifact.path} (existing ${artifact.kind} artifacts are protected from overwrite; delete or retarget the file to regenerate it)`;
@@ -10658,20 +11240,36 @@ function formatSkippedArtifactLine(artifact) {
 }
 async function runCLI(argv, runtime = {}) {
   const log = runtime.log ?? console.log;
+  const errorLog = runtime.errorLog ?? console.error;
   const runGenerator = runtime.runGenerator ?? runSchemaGenerator;
-  const parsed = parseCommand(argv);
+  let parsed;
+  try {
+    parsed = parseCommand(argv);
+  } catch (error) {
+    logCliError(formatGeneratorError(error), errorLog);
+    process.exitCode = 1;
+    return;
+  }
   if (parsed.command === "help") {
     log(usage(parsed.topic));
     return;
   }
   let result;
   try {
+    if (isDebugEnabled()) {
+      errorLog(
+        `[athena-js] generate starting (dryRun=${parsed.dryRun}${parsed.configPath ? ` config=${parsed.configPath}` : ""})`
+      );
+    }
     result = await runGenerator({
       configPath: parsed.configPath,
       dryRun: parsed.dryRun
     });
   } catch (error) {
-    throw formatGeneratorError(error, parsed.configPath);
+    const formatted = formatGeneratorError(error, parsed.configPath);
+    logCliError(formatted, errorLog);
+    process.exitCode = 1;
+    return;
   }
   if (parsed.dryRun) {
     log(`[dry-run] Generated ${result.files.length} files from ${result.configPath}`);
@@ -10695,6 +11293,7 @@ async function runCLI(argv, runtime = {}) {
   }
 }
 
+exports.logCliError = logCliError;
 exports.parseCommand = parseCommand;
 exports.runCLI = runCLI;
 exports.usage = usage;