@aouda/client 0.1.9 → 0.1.11

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.9",
+  version: "0.1.11",
   description: "Official TypeScript/JavaScript client library for Aouda",
   type: "module",
   main: "./dist/index.cjs",
@@ -354,6 +357,7 @@ var AuthHandler = class {
     this._tokenExpiry = null;
     this._authenticated = false;
     this._refreshPromise = null;
+    this._onAccessTokenRefreshed = null;
     this._serverUrl = serverUrl.replace(/\/+$/, "");
     this._timeout = timeout;
     this._authBasePath = config.basePath;
@@ -603,10 +607,16 @@ var AuthHandler = class {
     const thresholdSeconds = this._refreshThresholdMs / 1e3;
     return this._tokenExpiry <= nowSeconds + thresholdSeconds;
   }
+  setOnAccessTokenRefreshed(handler) {
+    this._onAccessTokenRefreshed = handler;
+  }
   async _doRefresh() {
     try {
       const result = await this.callRefreshEndpoint();
       this.handleSignInResult(result);
+      if (result.accessToken) {
+        this._onAccessTokenRefreshed?.(result.accessToken);
+      }
       return true;
     } catch {
       return false;
@@ -1207,7 +1217,15 @@ var ERROR_CODE_MAP = {
   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();
@@ -2100,6 +2118,8 @@ var TableSubscription = class {
     this._started = false;
     this._startPromise = null;
     this._lastVersion = 0;
+    this._pendingSnapshotRows = [];
+    this._forceFreshSubscribe = false;
     this.id = createStreamingId("sub");
     this._transport = transport;
     this._tableName = tableName;
@@ -2107,6 +2127,7 @@ var TableSubscription = class {
     this._onSnapshot = options.onSnapshot;
     this._onChange = options.onChange;
     this._onError = options.onError;
+    this._conflate = options.conflate;
     this._reconnectHandlerKey = `${this.id}::reconnect`;
   }
   get lastVersion() {
@@ -2156,7 +2177,9 @@ var TableSubscription = class {
       return;
     }
     try {
-      const resumeFrom = this._lastVersion > 0 ? this._lastVersion : void 0;
+      this._pendingSnapshotRows = [];
+      const resumeFrom = this._forceFreshSubscribe || this._lastVersion <= 0 ? void 0 : this._lastVersion;
+      this._forceFreshSubscribe = false;
       await this._sendSubscribe(resumeFrom);
     } catch (error) {
       const wrapped = error instanceof Error ? error : new AoudaConnectionError("Subscription reconnect failed");
@@ -2176,6 +2199,9 @@ var TableSubscription = class {
     if (resumeFrom !== void 0) {
       message.resume_from = resumeFrom;
     }
+    if (this._conflate !== void 0) {
+      message.conflate = this._conflate;
+    }
     await this._transport.send(message);
   }
   _handleMessage(message) {
@@ -2184,7 +2210,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);
@@ -2196,9 +2228,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",
@@ -2206,6 +2242,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 = {
@@ -2216,10 +2262,20 @@ var TableSubscription = class {
       key: message.key,
       version: message.version
     };
+    if (message.values_skipped !== void 0) {
+      event.values_skipped = message.values_skipped;
+    }
     this._onChange?.(event);
     this._queue.push(event);
   }
   _handleServerError(message) {
+    if (message.code === "SLOW_CONSUMER") {
+      this._pendingSnapshotRows = [];
+      this._lastVersion = 0;
+      this._forceFreshSubscribe = true;
+      return;
+    }
+    this._pendingSnapshotRows = [];
     const error = new AoudaConnectionError(
       `Subscription error (${message.code}): ${message.message}`
     );
@@ -2932,7 +2988,8 @@ var TableQuery = class _TableQuery {
       {
         onSnapshot: options.onSnapshot,
         onChange: options.onChange,
-        onError: options.onError
+        onError: options.onError,
+        conflate: options.conflate
       },
       mergedFilter
     );
@@ -4658,6 +4715,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;
@@ -4682,6 +4880,7 @@ var WebSocketTransport = class {
     // Resolved/rejected when the auth handshake completes.
     this._authResolve = null;
     this._authReject = null;
+    this._handshakeComplete = false;
     this._serverUrl = serverUrl;
     this._database = database;
     this._authHandler = options.authHandler;
@@ -4691,6 +4890,11 @@ var WebSocketTransport = class {
     this._maxMissedHeartbeats = options.maxMissedHeartbeats ?? DEFAULT_MAX_MISSED_HEARTBEATS;
     this._enableCompression = options.enableCompression ?? true;
     this._wireMode = options.wireMode ?? "json";
+    this._authHandler?.setOnAccessTokenRefreshed((token) => {
+      if (this._handshakeComplete && this._ws?.readyState === WS_READY_STATE_OPEN) {
+        void this.send({ type: "re_auth", token });
+      }
+    });
   }
   // ─── Public API ────────────────────────────────────────────────────────────
   /** Latest version number from the most recent server `heartbeat` message. */
@@ -4863,6 +5067,7 @@ var WebSocketTransport = class {
         const resolve = this._authResolve;
         this._authResolve = null;
         this._authReject = null;
+        this._handshakeComplete = true;
         if (resolve) resolve();
         break;
       }
@@ -4889,10 +5094,15 @@ var WebSocketTransport = class {
         break;
     }
     const id = "id" in msg ? msg.id : void 0;
-    if (id !== void 0 && id !== null) {
+    if (id !== void 0 && id !== null && id !== "") {
       this._handlers.get(id)?.(msg);
     } else {
       this._handlers.get("__global__")?.(msg);
+      for (const [key, handler] of this._handlers) {
+        if (key !== "__global__") {
+          handler(msg);
+        }
+      }
     }
   }
   // ─── Internal: reconnect ──────────────────────────────────────────────────
@@ -5420,6 +5630,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.
@@ -5562,6 +5785,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.
@@ -5983,6 +6218,8 @@ var version = package_default.version;
   MaterializedQueryState,
   MaterializedQueryType,
   MetricsAdminApi,
+  NamedMutationsApi,
+  NamedQueriesApi,
   NodeAdminApi,
   ReplicationAdminApi,
   RetryPolicy,
@@ -5993,6 +6230,7 @@ var version = package_default.version;
   WhereGroupBuilder,
   applyLocalNetworkAccess,
   coerceColumnarValue,
+  columnarToRows,
   createAoudaClient,
   createAoudaClusterMcpToolSet,
   installLocalNetworkFetch,