@aouda/client 0.1.8 → 0.1.10

package/dist/index.cjs

@@ -61,6 +61,8 @@ __export(index_exports, {
   MaterializedQueryState: () => MaterializedQueryState,
   MaterializedQueryType: () => MaterializedQueryType,
   MetricsAdminApi: () => MetricsAdminApi,
+  NamedMutationsApi: () => NamedMutationsApi,
+  NamedQueriesApi: () => NamedQueriesApi,
   NodeAdminApi: () => NodeAdminApi,
   ReplicationAdminApi: () => ReplicationAdminApi,
   RetryPolicy: () => RetryPolicy,
@@ -71,6 +73,7 @@ __export(index_exports, {
   WhereGroupBuilder: () => WhereGroupBuilder,
   applyLocalNetworkAccess: () => applyLocalNetworkAccess,
   coerceColumnarValue: () => coerceColumnarValue,
+  columnarToRows: () => columnarToRows,
   createAoudaClient: () => createAoudaClient,
   createAoudaClusterMcpToolSet: () => createAoudaClusterMcpToolSet,
   installLocalNetworkFetch: () => installLocalNetworkFetch,
@@ -83,7 +86,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@aouda/client",
-  version: "0.1.8",
+  version: "0.1.10",
   description: "Official TypeScript/JavaScript client library for Aouda",
   type: "module",
   main: "./dist/index.cjs",
@@ -215,12 +218,13 @@ var AoudaResponseError = class extends AoudaError {
   }
 };
 var AoudaApiError = class extends AoudaError {
-  constructor(message, code, statusCode, details, requestId) {
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds) {
     super(message);
     this.code = code;
     this.statusCode = statusCode;
     this.details = details;
     this.requestId = requestId;
+    this.retryAfterSeconds = retryAfterSeconds;
     this.name = "AoudaApiError";
   }
 };
@@ -243,8 +247,8 @@ var AoudaValidationError = class extends AoudaApiError {
   }
 };
 var AoudaServerError = class extends AoudaApiError {
-  constructor(message, code, statusCode, details, requestId) {
-    super(message, code, statusCode, details, requestId);
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds) {
+    super(message, code, statusCode, details, requestId, retryAfterSeconds);
     this.name = "AoudaServerError";
   }
 };
@@ -1199,12 +1203,22 @@ var ERROR_CODE_MAP = {
   SERVICE_UNAVAILABLE: AoudaServerError,
   TIMEOUT: AoudaServerError,
   OVERLOADED: AoudaServerError,
+  MEMORY_BUDGET_EXCEEDED: AoudaServerError,
+  WAL_CAPACITY_EXCEEDED: AoudaServerError,
   AUTH_TOKEN_MISSING: AoudaAuthenticationError,
   AUTH_TOKEN_EXPIRED: AoudaAuthenticationError,
   AUTH_TOKEN_INVALID: AoudaAuthenticationError,
   AUTH_TOKEN_REVOKED: AoudaAuthenticationError,
   AUTH_API_KEY_INVALID: AoudaAuthenticationError,
-  AUTH_REQUIRED: AoudaAuthenticationError
+  AUTH_REQUIRED: AoudaAuthenticationError,
+  NAMED_QUERY_NOT_FOUND: AoudaNotFoundError,
+  NAMED_MUTATION_NOT_FOUND: AoudaNotFoundError,
+  NAMED_QUERY_BATCH_EMPTY: AoudaValidationError,
+  NAMED_QUERY_BATCH_TOO_LARGE: AoudaValidationError,
+  NAMED_QUERY_BATCH_MUTATION: AoudaValidationError,
+  NAMED_QUERY_BIND_FAILED: AoudaValidationError,
+  NAMED_QUERY_PARAM_REQUIRED: AoudaValidationError,
+  NAMED_MUTATION_BIND_FAILED: AoudaValidationError
 };
 function createComposedAbortController(...signals) {
   const controller = new AbortController();
@@ -1226,13 +1240,22 @@ function createComposedAbortController(...signals) {
   }
   return controller;
 }
-function createApiError(statusCode, statusText, body) {
+function parseRetryAfterSeconds(header) {
+  if (header == null || header.trim() === "") return void 0;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed)) return void 0;
+  const n = Number.parseInt(trimmed, 10);
+  if (!Number.isFinite(n) || n < 0) return void 0;
+  return n;
+}
+function createApiError(statusCode, statusText, body, retryAfterHeader) {
   const message = body.error ?? `${statusCode} ${statusText}`;
   const code = body.code ?? "UNKNOWN";
   const details = body.details;
   const requestId = body.requestId;
+  const retryAfterSeconds = parseRetryAfterSeconds(retryAfterHeader ?? null);
   const Ctor = ERROR_CODE_MAP[code] ?? AoudaApiError;
-  return new Ctor(message, code, statusCode, details, requestId);
+  return new Ctor(message, code, statusCode, details, requestId, retryAfterSeconds);
 }
 var HttpTransport = class {
   constructor(options) {
@@ -1325,7 +1348,8 @@ var HttpTransport = class {
           throw createApiError(
             response.status,
             response.statusText,
-            errorBody
+            errorBody,
+            response.headers.get("Retry-After")
           );
         }
         throw new AoudaResponseError(
@@ -1435,7 +1459,8 @@ var HttpTransport = class {
         throw createApiError(
           response.status,
           response.statusText,
-          errorBody
+          errorBody,
+          response.headers.get("Retry-After")
         );
       }
       throw new AoudaResponseError(
@@ -1781,6 +1806,17 @@ var CIRCUIT_BREAKER_POLICY_DISABLED = {
 
 // src/resilience/resilient-transport.ts
 var REQUEST_ID_HEADER3 = "X-Request-Id";
+function isCapacityBackPressure(error) {
+  return error instanceof AoudaApiError && (error.code === "MEMORY_BUDGET_EXCEEDED" || error.code === "WAL_CAPACITY_EXCEEDED");
+}
+function retryDelayMs(retryPolicy, attempt, error) {
+  const backoff = calculateDelay(retryPolicy, attempt);
+  if (!isCapacityBackPressure(error) || !(error instanceof AoudaApiError)) {
+    return backoff;
+  }
+  const headerMs = error.retryAfterSeconds != null ? error.retryAfterSeconds * 1e3 : 0;
+  return Math.max(backoff, headerMs);
+}
 function delayMs(ms, signal) {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve, reject) => {
@@ -1835,7 +1871,7 @@ var ResilientTransport = class {
       } catch (error) {
         lastError = error;
         const retryable = isRetryable(error);
-        if (retryable) {
+        if (retryable && !isCapacityBackPressure(error)) {
           this.circuitBreaker.recordFailure(error);
         }
         if (!retryable) {
@@ -1845,7 +1881,7 @@ var ResilientTransport = class {
         if (attempt > this.retryPolicy.maxRetries) {
           throw error;
         }
-        const delay = calculateDelay(this.retryPolicy, attempt);
+        const delay = retryDelayMs(this.retryPolicy, attempt, error);
         try {
           await delayMs(delay, config.signal);
         } catch {
@@ -1881,7 +1917,7 @@ var ResilientTransport = class {
       } catch (error) {
         lastError = error;
         const retryable = isRetryable(error);
-        if (retryable) {
+        if (retryable && !isCapacityBackPressure(error)) {
           this.circuitBreaker.recordFailure(error);
         }
         if (!retryable) {
@@ -1891,7 +1927,7 @@ var ResilientTransport = class {
         if (attempt > this.retryPolicy.maxRetries) {
           throw error;
         }
-        const delay = calculateDelay(this.retryPolicy, attempt);
+        const delay = retryDelayMs(this.retryPolicy, attempt, error);
         try {
           await delayMs(delay, config.signal);
         } catch {
@@ -2075,6 +2111,7 @@ var TableSubscription = class {
     this._started = false;
     this._startPromise = null;
     this._lastVersion = 0;
+    this._pendingSnapshotRows = [];
     this.id = createStreamingId("sub");
     this._transport = transport;
     this._tableName = tableName;
@@ -2131,6 +2168,7 @@ var TableSubscription = class {
       return;
     }
     try {
+      this._pendingSnapshotRows = [];
       const resumeFrom = this._lastVersion > 0 ? this._lastVersion : void 0;
       await this._sendSubscribe(resumeFrom);
     } catch (error) {
@@ -2159,7 +2197,13 @@ var TableSubscription = class {
     }
     switch (message.type) {
       case "snapshot":
-        this._handleSnapshot(message);
+        this._handleSnapshotPage(message);
+        return;
+      case "snapshot_complete":
+        this._handleSnapshotComplete(message);
+        return;
+      case "gap":
+        void this._handleGap(message);
         return;
       case "change":
         this._handleChange(message);
@@ -2171,9 +2215,13 @@ var TableSubscription = class {
         return;
     }
   }
-  _handleSnapshot(message) {
+  _handleSnapshotPage(message) {
+    this._pendingSnapshotRows.push(...message.rows);
+  }
+  _handleSnapshotComplete(message) {
     this._lastVersion = message.version;
-    const rows = message.rows;
+    const rows = this._pendingSnapshotRows;
+    this._pendingSnapshotRows = [];
     this._onSnapshot?.(rows, message.version);
     this._queue.push({
       type: "snapshot",
@@ -2181,6 +2229,16 @@ var TableSubscription = class {
       version: message.version
     });
   }
+  async _handleGap(message) {
+    this._pendingSnapshotRows = [];
+    this._lastVersion = message.last_seq;
+    try {
+      await this._sendSubscribe(message.last_seq);
+    } catch (error) {
+      const wrapped = error instanceof Error ? error : new AoudaConnectionError("Subscription gap resume failed");
+      this._notifyError(wrapped);
+    }
+  }
   _handleChange(message) {
     this._lastVersion = message.version;
     const event = {
@@ -2195,6 +2253,7 @@ var TableSubscription = class {
     this._queue.push(event);
   }
   _handleServerError(message) {
+    this._pendingSnapshotRows = [];
     const error = new AoudaConnectionError(
       `Subscription error (${message.code}): ${message.message}`
     );
@@ -4633,6 +4692,147 @@ var MaterializedQueriesApi = class {
   }
 };
 
+// src/named-queries.ts
+var MAX_NAMED_QUERY_BATCH_SIZE = 32;
+function raiseDeprecationWarnings(sink, warnings) {
+  if (warnings == null) return;
+  for (const warning of warnings) {
+    if (warning.code !== "NAMED_QUERY_DEPRECATED" && warning.code !== "NAMED_MUTATION_DEPRECATED") {
+      continue;
+    }
+    const sunset = warning.sunsetAt != null ? ` sunsetAt=${warning.sunsetAt}` : "";
+    const hash = warning.hash != null && warning.hash.length > 0 ? ` hash=${warning.hash}` : "";
+    sink({
+      code: warning.code,
+      hash: warning.hash,
+      sunsetAt: warning.sunsetAt,
+      message: `${warning.code}:${hash}${sunset}`.trim()
+    });
+  }
+}
+function emptyStats() {
+  return {
+    rowsScanned: 0,
+    rowsReturned: 0,
+    segmentsAccessed: 0,
+    executionMs: 0
+  };
+}
+var NamedQueriesApi = class {
+  constructor(transport, database, onWarning) {
+    this.transport = transport;
+    this.database = database;
+    this.onWarning = onWarning;
+  }
+  async execute(hash, args, options) {
+    if (typeof hash !== "string" || hash.trim().length === 0) {
+      throw new Error("Named query hash must be a non-empty string");
+    }
+    const prefix = databasePath2(this.database);
+    const path = `${prefix}/named-queries/${encodeURIComponent(hash)}/query?format=columnar`;
+    const response = await this.transport.post(
+      path,
+      { args: args ?? {} },
+      { signal: options?.signal }
+    );
+    const rows = columnarToRows(response);
+    raiseDeprecationWarnings(this.onWarning, response.warnings);
+    return {
+      rows,
+      stats: response.stats,
+      warnings: response.warnings
+    };
+  }
+  async batch(items, options) {
+    if (items.length === 0) {
+      throw new AoudaValidationError(
+        "Named query batch requires a non-empty queries array.",
+        "NAMED_QUERY_BATCH_EMPTY",
+        400
+      );
+    }
+    if (items.length > MAX_NAMED_QUERY_BATCH_SIZE) {
+      throw new AoudaValidationError(
+        `Named query batch exceeds ${MAX_NAMED_QUERY_BATCH_SIZE} elements.`,
+        "NAMED_QUERY_BATCH_TOO_LARGE",
+        400
+      );
+    }
+    const prefix = databasePath2(this.database);
+    const path = `${prefix}/named-queries/batch?format=columnar`;
+    const envelope = await this.transport.post(
+      path,
+      { queries: items },
+      { signal: options?.signal }
+    );
+    return (envelope.results ?? []).map((slot) => {
+      if (slot.code != null && slot.code.length > 0) {
+        return {
+          isError: true,
+          code: slot.code,
+          error: slot.error
+        };
+      }
+      const columnar = {
+        columns: slot.columns ?? [],
+        types: slot.types ?? [],
+        data: slot.data ?? [],
+        rowCount: slot.rowCount ?? 0,
+        stats: slot.stats ?? emptyStats(),
+        warnings: slot.warnings
+      };
+      const result = {
+        rows: columnarToRows(columnar),
+        stats: columnar.stats,
+        warnings: slot.warnings
+      };
+      raiseDeprecationWarnings(this.onWarning, slot.warnings);
+      return { isError: false, result };
+    });
+  }
+};
+var NamedMutationsApi = class {
+  constructor(transport, database, onWarning) {
+    this.transport = transport;
+    this.database = database;
+    this.onWarning = onWarning;
+  }
+  async execute(hash, args) {
+    if (typeof hash !== "string" || hash.trim().length === 0) {
+      throw new Error("Named mutation hash must be a non-empty string");
+    }
+    const prefix = databasePath2(this.database);
+    const path = `${prefix}/named-mutations/${encodeURIComponent(hash)}/execute`;
+    const wire = await this.transport.post(path, {
+      args: args ?? {}
+    });
+    let op = "unknown";
+    let rowsAffected = 0;
+    if (wire.rowsInserted != null) {
+      op = "insert";
+      rowsAffected = wire.rowsInserted;
+    } else if (wire.rowsUpdated != null) {
+      op = "update";
+      rowsAffected = wire.rowsUpdated;
+    } else if (wire.rowsDeleted != null) {
+      op = "delete";
+      rowsAffected = wire.rowsDeleted;
+    }
+    raiseDeprecationWarnings(this.onWarning, wire.warnings);
+    const returning = wire.rows == null ? void 0 : {
+      rows: columnarToRows(wire.rows),
+      stats: wire.rows.stats,
+      warnings: wire.rows.warnings
+    };
+    return {
+      op,
+      rowsAffected,
+      returning,
+      warnings: wire.warnings
+    };
+  }
+};
+
 // src/streaming/websocket-transport.ts
 var import_msgpack = require("@msgpack/msgpack");
 var DEFAULT_PING_INTERVAL_MS = 2e4;
@@ -5395,6 +5595,19 @@ var AoudaClient = class {
       this.transport,
       this.database
     );
+    const onNamedArtifactWarning = options.onNamedArtifactWarning ?? ((warning) => {
+      console.warn(warning.message);
+    });
+    this._namedQueries = new NamedQueriesApi(
+      this.transport,
+      this.database,
+      onNamedArtifactWarning
+    );
+    this._namedMutations = new NamedMutationsApi(
+      this.transport,
+      this.database,
+      onNamedArtifactWarning
+    );
   }
   /**
    * Connects to the Aouda server.
@@ -5537,6 +5750,18 @@ var AoudaClient = class {
   get materializedQueries() {
     return this._materializedQueries;
   }
+  /**
+   * Hash-only named-query execute and batch. Names are codegen aliases (D-5).
+   */
+  get namedQueries() {
+    return this._namedQueries;
+  }
+  /**
+   * Hash-only named-mutation execute. No batch.
+   */
+  get namedMutations() {
+    return this._namedMutations;
+  }
   /**
    * Access auth operations (signUp, signIn, signOut, refresh, me, changePassword).
    * @returns The auth API.
@@ -5958,6 +6183,8 @@ var version = package_default.version;
   MaterializedQueryState,
   MaterializedQueryType,
   MetricsAdminApi,
+  NamedMutationsApi,
+  NamedQueriesApi,
   NodeAdminApi,
   ReplicationAdminApi,
   RetryPolicy,
@@ -5968,6 +6195,7 @@ var version = package_default.version;
   WhereGroupBuilder,
   applyLocalNetworkAccess,
   coerceColumnarValue,
+  columnarToRows,
   createAoudaClient,
   createAoudaClusterMcpToolSet,
   installLocalNetworkFetch,