@object-ui/data-objectstack 16.1.0 → 17.1.0

package/dist/index.js

@@ -5,7 +5,32 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/index.ts
 import { ObjectStackClient } from "@objectstack/client";
 
+// ../types/src/index.ts
+import {
+  defineStack,
+  ObjectStackSchema,
+  ObjectStackDefinitionSchema
+} from "@objectstack/spec";
+
+// ../types/src/error-code.ts
+function errorCodeIs(err, code) {
+  const raw = err?.code;
+  if (typeof raw !== "string" || raw.length === 0) return false;
+  return raw.toUpperCase() === code.toUpperCase();
+}
+function errorCodeIsAnyOf(err, codes) {
+  return codes.some((c) => errorCodeIs(err, c));
+}
+
 // ../core/src/utils/filter-converter.ts
+var FilterOperatorError = class extends Error {
+  constructor(message) {
+    super(message);
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    this.name = "FilterOperatorError";
+  }
+};
 function convertOperatorToAST(operator) {
   const operatorMap = {
     "$eq": "=",
@@ -35,11 +60,9 @@ function convertFiltersToAST(filter) {
     if (typeof value === "object" && !Array.isArray(value)) {
       for (const [operator, operatorValue] of Object.entries(value)) {
         if (operator === "$regex") {
-          console.warn(
-            `[ObjectUI] Warning: $regex operator is not fully supported. Converting to 'contains' which only supports substring matching, not regex patterns. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. Consider using $contains or $startsWith instead.`
+          throw new FilterOperatorError(
+            `[ObjectUI] The '$regex' filter operator is not supported. It used to be converted to 'contains', which matches a literal substring rather than a pattern \u2014 a different result, not a degraded one. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. Use $contains, $startsWith or $endsWith.`
           );
-          conditions.push([field, "contains", operatorValue]);
-          continue;
         }
         if (operator === "$null") {
           conditions.push([field, operatorValue ? "is_null" : "is_not_null", true]);
@@ -53,7 +76,7 @@ function convertFiltersToAST(filter) {
         if (astOperator) {
           conditions.push([field, astOperator, operatorValue]);
         } else {
-          throw new Error(
+          throw new FilterOperatorError(
             `[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, $contains, $notContains, $startsWith, $endsWith, $null, $exists. If you need exact object matching, use the value directly without an operator.`
           );
         }
@@ -1061,10 +1084,9 @@ function createObjectStackUserStateAdapter(options) {
     return [];
   };
   const upsert = async (items) => {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
     if (cachedRowId !== null) {
       try {
-        await dataSource.update(resource, cachedRowId, { value: items, updated_at: now });
+        await dataSource.update(resource, cachedRowId, { value: items });
         return;
       } catch (updateError) {
         cachedRowId = null;
@@ -1074,15 +1096,14 @@ function createObjectStackUserStateAdapter(options) {
     const existing = await findExisting();
     if (existing && existing.id !== void 0 && existing.id !== null) {
       cachedRowId = existing.id;
-      await dataSource.update(resource, existing.id, { value: items, updated_at: now });
+      await dataSource.update(resource, existing.id, { value: items });
       return;
     }
     try {
       const created = await dataSource.create(resource, {
         user_id: userId,
         key,
-        value: items,
-        updated_at: now
+        value: items
       });
       const newId = created?.id;
       if (newId !== void 0 && newId !== null) cachedRowId = newId;
@@ -1090,7 +1111,7 @@ function createObjectStackUserStateAdapter(options) {
       const recovered = await findExisting();
       if (recovered && recovered.id !== void 0 && recovered.id !== null) {
         cachedRowId = recovered.id;
-        await dataSource.update(resource, recovered.id, { value: items, updated_at: now });
+        await dataSource.update(resource, recovered.id, { value: items });
         return;
       }
       throw createError;
@@ -1419,38 +1440,107 @@ var FILTER_OPERATOR_ALIASES = {
   is_null: "isnull",
   isnull: "isnull",
   is_not_null: "isnotnull",
-  isnotnull: "isnotnull"
+  isnotnull: "isnotnull",
+  // Date comparisons. `before`/`after` are CANONICAL members of the spec's
+  // `VIEW_FILTER_OPERATORS` (ui/view.zod.ts), so a stored view legitimately
+  // carries them — but they are absent from `VALID_AST_OPERATORS`
+  // (data/filter.zod.ts), which gates `isFilterAST()`. Without these two
+  // entries they reached the wire unchanged, the server's AST gate rejected
+  // the shape, and driver-sql skipped the filter ENTIRELY — an unfiltered
+  // result set with no error anywhere. objectstack#3948.
+  before: "<",
+  after: ">"
 };
 function normalizeFilterOperator(op) {
   if (typeof op !== "string") return null;
   const lower = op.toLowerCase();
   return FILTER_OPERATOR_ALIASES[lower] ?? FILTER_OPERATOR_ALIASES[op] ?? op;
 }
+var MalformedFilterError = class extends Error {
+  constructor(entry, index) {
+    const shown = JSON.stringify(entry) ?? String(entry);
+    super(
+      `Filter entry ${index} is not a usable filter rule (${shown}). Expected { field, operator, value } with a non-empty field.`
+    );
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    __publicField(this, "entry");
+    __publicField(this, "index");
+    this.name = "MalformedFilterError";
+    this.entry = entry;
+    this.index = index;
+  }
+};
+function isMalformedFilterError(error) {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  return e.code === "INVALID_FILTER" || e.name === "MalformedFilterError";
+}
 function objectFilterEntryToAST(entry) {
   if (!entry || typeof entry !== "object") return null;
-  const field = entry.field ?? entry.name;
+  const field = entry.field;
   const rawOp = entry.operator ?? entry.op ?? "=";
   const op = normalizeFilterOperator(rawOp);
   if (!field || !op) return null;
   return [String(field), op, entry.value];
 }
+function isObjectFilterEntryForm(filter) {
+  const first = filter[0];
+  return filter.length > 0 && typeof first === "object" && first !== null && !Array.isArray(first) && first.field !== void 0;
+}
+function objectFilterEntriesToAST(entries) {
+  const nodes = entries.map((entry, i) => {
+    if (Array.isArray(entry)) return translateFilterChild(entry);
+    const tuple = objectFilterEntryToAST(entry);
+    if (!tuple) throw new MalformedFilterError(entry, i);
+    return tuple;
+  });
+  return nodes.length === 1 ? nodes[0] : ["and", ...nodes];
+}
+var LOGICAL_AST_HEADS = /* @__PURE__ */ new Set(["and", "or"]);
+function translateFilterArray(filter) {
+  if (isObjectFilterEntryForm(filter)) return objectFilterEntriesToAST(filter);
+  const head = filter[0];
+  if (typeof head === "string" && LOGICAL_AST_HEADS.has(head.toLowerCase())) {
+    return [head, ...filter.slice(1).map(translateFilterChild)];
+  }
+  if (filter.every((child) => Array.isArray(child))) return filter.map(translateFilterChild);
+  return filter;
+}
+function translateFilterChild(child) {
+  if (Array.isArray(child)) return child.length > 0 ? translateFilterArray(child) : child;
+  if (child && typeof child === "object" && child.field !== void 0) {
+    const tuple = objectFilterEntryToAST(child);
+    if (tuple) return tuple;
+  }
+  return child;
+}
 function translateFilterToAST(filter) {
   if (filter === void 0 || filter === null) return void 0;
   if (Array.isArray(filter)) {
     if (filter.length === 0) return void 0;
-    const first = filter[0];
-    const isObjectForm = filter.length > 0 && typeof first === "object" && first !== null && !Array.isArray(first) && first.field !== void 0;
-    if (isObjectForm) {
-      const tuples = filter.map((entry) => objectFilterEntryToAST(entry)).filter((t) => t !== null);
-      if (tuples.length === 0) return void 0;
-      if (tuples.length === 1) return tuples[0];
-      return ["and", ...tuples];
-    }
-    return filter;
+    return translateFilterArray(filter);
   }
   if (typeof filter === "object") {
     if (Object.keys(filter).length === 0) return void 0;
-    return filter;
+    return convertFiltersToAST(filter);
+  }
+  return void 0;
+}
+function serializeOrderBy(orderby) {
+  if (orderby === void 0 || orderby === null) return void 0;
+  if (typeof orderby === "string") {
+    const trimmed = orderby.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  const shorthand = (field, order) => String(order).toLowerCase() === "desc" ? `-${field}` : field;
+  if (Array.isArray(orderby)) {
+    const parts = orderby.map((item) => typeof item === "string" ? item.trim() : shorthand(item.field, item.order)).filter((s) => s.length > 0);
+    return parts.length > 0 ? parts.join(",") : void 0;
+  }
+  if (typeof orderby === "object") {
+    const parts = Object.entries(orderby).map(([field, order]) => shorthand(field, order));
+    return parts.length > 0 ? parts.join(",") : void 0;
   }
   return void 0;
 }
@@ -1486,7 +1576,46 @@ function is404Error(error) {
     return true;
   }
   const code = typeof err.code === "string" ? err.code : "";
-  return code === "object_not_found" || code === "record_not_found";
+  return errorCodeIsAnyOf({ code }, ["OBJECT_NOT_FOUND", "RECORD_NOT_FOUND"]);
+}
+var AnalyticsNotInstalledError = class extends Error {
+  constructor(surface, detail) {
+    super(
+      `Analytics capability is not installed on this deployment \u2014 ${surface} is unavailable. Install @objectstack/service-analytics and mount AnalyticsServicePlugin to enable it.` + (detail ? ` (server said: ${detail})` : "")
+    );
+    __publicField(this, "code", "ANALYTICS_NOT_INSTALLED");
+    /** The surface that was unavailable, for the message a host renders. */
+    __publicField(this, "surface");
+    this.name = "AnalyticsNotInstalledError";
+    this.surface = surface;
+  }
+};
+function isAnalyticsNotInstalledError(error) {
+  if (!error || typeof error !== "object") return false;
+  return error.code === "ANALYTICS_NOT_INSTALLED";
+}
+var AnalyticsQueryRejectedError = class extends Error {
+  constructor(detail, serverCode) {
+    super(
+      `Analytics rejected the query: ${detail ?? "the request body does not match the AnalyticsQuery contract"}`
+    );
+    __publicField(this, "code", "ANALYTICS_QUERY_REJECTED");
+    /** The server's own error code (e.g. `VALIDATION_FAILED`), when it sent one. */
+    __publicField(this, "serverCode");
+    this.name = "AnalyticsQueryRejectedError";
+    this.serverCode = serverCode;
+  }
+};
+function classifyAnalyticsFailure(error) {
+  const err = error ?? {};
+  const code = typeof err.code === "string" ? err.code : void 0;
+  const message = typeof err.message === "string" ? err.message : void 0;
+  const status = typeof err.httpStatus === "number" ? err.httpStatus : typeof err.status === "number" ? err.status : typeof err.statusCode === "number" ? err.statusCode : void 0;
+  if (code === "VALIDATION_FAILED" || status === 400) return { kind: "rejected", code, message };
+  if (status === 404 || status === 501 || code === "NOT_IMPLEMENTED" || code === "ROUTE_NOT_FOUND") {
+    return { kind: "not-installed", code, message };
+  }
+  return { kind: "unknown", code, message };
 }
 var ConcurrentUpdateError = class extends Error {
   constructor(opts) {
@@ -1508,9 +1637,25 @@ function isConcurrentUpdateError(error) {
 function normaliseClientError(error) {
   if (!error || typeof error !== "object") return error;
   const e = error;
+  const details = e.details ?? {};
+  if (e.code === "VALIDATION_FAILED" || e.name === "ValidationError") {
+    const rawFields = Array.isArray(details.fields) ? details.fields : Array.isArray(e.fields) ? e.fields : [];
+    const validationErrors = rawFields.map((f) => {
+      const rec = f ?? {};
+      const field = typeof rec.field === "string" ? rec.field : void 0;
+      if (!field) return null;
+      const message = typeof rec.message === "string" && rec.message.trim() ? rec.message : typeof rec.code === "string" ? rec.code : "";
+      return { field, message };
+    }).filter((x) => x !== null);
+    return new ValidationError(
+      typeof e.message === "string" ? e.message : "Validation failed",
+      validationErrors[0]?.field,
+      validationErrors,
+      { fields: rawFields }
+    );
+  }
   if (e.code !== "CONCURRENT_UPDATE" && e.httpStatus !== 409) return error;
   if (e.code !== "CONCURRENT_UPDATE") return error;
-  const details = e.details ?? {};
   return new ConcurrentUpdateError({
     currentVersion: typeof details.currentVersion === "string" ? details.currentVersion : null,
     currentRecord: details.currentRecord ?? null,
@@ -1524,7 +1669,7 @@ function createQuietHttpLogger() {
     const errBody = meta.error;
     if (errBody && typeof errBody === "object") {
       const code = errBody.code;
-      if (code === "object_not_found" || code === "record_not_found") return true;
+      if (errorCodeIsAnyOf({ code }, ["OBJECT_NOT_FOUND", "RECORD_NOT_FOUND"])) return true;
     }
     return false;
   };
@@ -1568,6 +1713,8 @@ var ObjectStackAdapter = class {
     __publicField(this, "reconnectAttempts", 0);
     __publicField(this, "baseUrl");
     __publicField(this, "token");
+    /** One "analytics capability is missing" console line per adapter, not per widget. */
+    __publicField(this, "analyticsCapabilityWarned", false);
     __publicField(this, "fetchImpl");
     // In-flight find() requests keyed by resource + serialized params.
     // Coalesces concurrent identical reads (e.g. React StrictMode double-mount,
@@ -1599,6 +1746,10 @@ var ObjectStackAdapter = class {
     // calendar) auto-refresh — the interface ListView relies on to reflect
     // inline-edit "Save All" writes without a manual reload.
     __publicField(this, "mutationListeners", /* @__PURE__ */ new Set());
+    // Subscribers registered via onWriteWarning(). Emitted after a create/update
+    // whose response carried `droppedFields` (framework #3431/#3455) so the app
+    // shell can surface a toast instead of the strip passing silently.
+    __publicField(this, "writeWarningListeners", /* @__PURE__ */ new Set());
     this.client = new ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
@@ -1770,6 +1921,77 @@ var ObjectStackAdapter = class {
     promise.then(cleanup, cleanup);
     return promise;
   }
+  /**
+   * Full-text search across every searchable object in a single round-trip.
+   *
+   * Hits `GET /api/v1/search?q=`, the platform's global search endpoint served
+   * by the registered search service (the pinyin full-text plugin) and backed
+   * by `metadata-protocol`'s `searchAll`. Unlike `find(resource, { $search })`
+   * — a per-object metadata-driven search (ADR-0061) — this consults the search
+   * index and ranks hits across objects, so it surfaces records the per-object
+   * fanout misses. Global affordances (⌘K command palette, search page) prefer
+   * this path (framework #3371).
+   *
+   * Returns `{ query, hits }`. A backend without the search plugin installed
+   * answers `404`; we treat that as "no global search here" and return an empty
+   * hit set so callers can fall back to a per-object fanout rather than surface
+   * an error.
+   */
+  async searchAll(query, options) {
+    const trimmed = (query ?? "").trim();
+    if (trimmed === "") return { query: "", hits: [] };
+    await this.connect();
+    const queryParams = new URLSearchParams();
+    queryParams.set("q", trimmed);
+    if (options?.limit != null && options.limit > 0) {
+      queryParams.set("limit", String(options.limit));
+    }
+    if (options?.objects && options.objects.length > 0) {
+      queryParams.set("objects", options.objects.join(","));
+    }
+    const baseUrl = (this.baseUrl || "").replace(/\/$/, "");
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const searchPath = hasApiVersionSuffix ? "/search" : "/api/v1/search";
+    const url = `${baseUrl}${searchPath}?${queryParams.toString()}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    const res = await this.fetchImpl(url, { method: "GET", headers });
+    if (!res.ok) {
+      if (res.status === 404) return { query: trimmed, hits: [] };
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(
+        errorBody?.error?.message || errorBody?.message || res.statusText
+      );
+      err.status = res.status;
+      throw err;
+    }
+    const body = await res.json();
+    const payload = body && typeof body === "object" && typeof body.success === "boolean" && "data" in body ? body.data : body;
+    const rawHits = Array.isArray(payload?.hits) ? payload.hits : Array.isArray(payload) ? payload : [];
+    const hits = [];
+    for (const entry of rawHits) {
+      if (!entry || typeof entry !== "object") continue;
+      const h = entry;
+      const object = h.object ?? h.objectName ?? h.object_name;
+      const id = h.id ?? h.record?.id ?? h.record?._id;
+      if (typeof object !== "string" || id == null) continue;
+      hits.push({
+        object,
+        id: String(id),
+        title: typeof h.title === "string" ? h.title : void 0,
+        snippet: typeof h.snippet === "string" ? h.snippet : void 0,
+        record: h.record && typeof h.record === "object" ? h.record : void 0
+      });
+    }
+    return {
+      query: typeof payload?.query === "string" ? payload.query : trimmed,
+      hits
+    };
+  }
   /**
    * Find a single record by ID.
    */
@@ -1833,11 +2055,84 @@ var ObjectStackAdapter = class {
       this.mutationListeners.delete(callback);
     };
   }
+  /**
+   * Notify all write-warning subscribers. Isolated like {@link emitMutation}: a
+   * throwing listener must not break the write or starve the others.
+   */
+  emitWriteWarning(event) {
+    for (const listener of this.writeWarningListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn("ObjectStackAdapter: write-warning listener error", err);
+      }
+    }
+  }
+  /**
+   * Read `droppedFields` off a create/update response (framework #3431/#3455)
+   * and, when present, notify write-warning subscribers. Tolerant of a client
+   * whose response type predates `droppedFields`: the field is read structurally
+   * and validated, so an older client (or a backend that never drops) is a no-op.
+   */
+  notifyDroppedFields(operation, resource, result, id) {
+    const dropped = result?.droppedFields;
+    if (!Array.isArray(dropped) || dropped.length === 0) return;
+    const droppedFields = dropped.filter(
+      (e) => !!e && typeof e === "object" && Array.isArray(e.fields) && e.fields.length > 0
+    );
+    if (droppedFields.length === 0) return;
+    this.emitWriteWarning({ operation, resource, ...id !== void 0 ? { id } : {}, droppedFields });
+  }
+  /**
+   * Same, for the cross-object transactional batch (framework #3794). Its
+   * response hangs the events off a top-level `droppedFields` list, each tagged
+   * with the `index` of the operation it came from — `results` entries are bare
+   * record echoes with nowhere to hang a per-row list.
+   *
+   * This is the path that matters most for the warning: `batchTransaction` is
+   * how the console's record form saves a master-detail record, so a
+   * `readonlyWhen`-locked field edited in that form was stripped server-side
+   * while the UI reported a plain success. The operation kind is taken from the
+   * originating op so the toast doesn't call an update a create.
+   */
+  notifyBatchDroppedFields(operations, payload) {
+    const dropped = payload?.droppedFields;
+    if (!Array.isArray(dropped) || dropped.length === 0) return;
+    for (const entry of dropped) {
+      if (!entry || typeof entry !== "object") continue;
+      const e = entry;
+      if (!Array.isArray(e.fields) || e.fields.length === 0) continue;
+      const op = typeof e.index === "number" ? operations[e.index] : void 0;
+      const operation = (op?.action ?? "create") === "create" ? "create" : "update";
+      this.emitWriteWarning({
+        operation,
+        resource: e.object ?? op?.object ?? "",
+        ...op?.id !== void 0 && op?.id !== null ? { id: op.id } : {},
+        droppedFields: [{ object: e.object, fields: e.fields, reason: e.reason }]
+      });
+    }
+  }
+  /**
+   * Subscribe to write-warning events (a create/update dropped caller-supplied
+   * fields — #3431/#3455). Returns an unsubscribe function. The app shell uses
+   * this to toast the user; the write itself already succeeded.
+   */
+  onWriteWarning(callback) {
+    this.writeWarningListeners.add(callback);
+    return () => {
+      this.writeWarningListeners.delete(callback);
+    };
+  }
   async create(resource, data) {
     await this.connect();
-    const result = await this.client.data.create(resource, data);
-    this.emitMutation({ type: "create", resource, record: { ...result.record } });
-    return result.record;
+    try {
+      const result = await this.client.data.create(resource, data);
+      this.emitMutation({ type: "create", resource, record: { ...result.record } });
+      this.notifyDroppedFields("create", resource, result, result.record?.id);
+      return result.record;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
   }
   /**
    * Update an existing record.
@@ -1860,6 +2155,7 @@ var ObjectStackAdapter = class {
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
       this.emitMutation({ type: "update", resource, id, record: { ...result.record } });
+      this.notifyDroppedFields("update", resource, result, id);
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -2017,6 +2313,7 @@ var ObjectStackAdapter = class {
     try {
       const payload = await this.client.data.batchTransaction(operations);
       this.emitBatchMutations(operations, payload?.results);
+      this.notifyBatchDroppedFields(operations, payload);
       return payload;
     } catch (err) {
       const status = this.errorStatusOf(err);
@@ -2048,7 +2345,7 @@ var ObjectStackAdapter = class {
     return emulateBatchTransaction(this, operations);
   }
   /**
-   * Emit one MutationEvent per committed operation so the invalidation bus
+   * Emit one DataSourceMutationEvent per committed operation so the invalidation bus
    * (#2269) sees writes that went through /batch exactly like single
    * create/update/delete calls — master-detail ModalForm saves otherwise leave
    * related lists and count badges stale (#2582). `results` is index-aligned
@@ -2401,20 +2698,8 @@ var ObjectStackAdapter = class {
       const selectFields = params.$select.includes("id") ? params.$select : ["id", ...params.$select];
       queryParams.set("select", selectFields.join(","));
     }
-    if (params.$orderby) {
-      if (Array.isArray(params.$orderby)) {
-        const sortStr = params.$orderby.map((item) => {
-          if (typeof item === "string") return item;
-          const field = item.field;
-          const order = item.order || "asc";
-          return order === "desc" ? `-${field}` : field;
-        }).join(",");
-        queryParams.set("sort", sortStr);
-      } else {
-        const sortStr = Object.entries(params.$orderby).map(([field, order]) => order === "desc" ? `-${field}` : field).join(",");
-        queryParams.set("sort", sortStr);
-      }
-    }
+    const sortStr = serializeOrderBy(params.$orderby);
+    if (sortStr) queryParams.set("sort", sortStr);
     if (params.$filter !== void 0 && params.$filter !== null) {
       const translated = translateFilterToAST(params.$filter);
       if (translated !== void 0) {
@@ -2478,6 +2763,13 @@ var ObjectStackAdapter = class {
         queryParams.set("filter", JSON.stringify(translated));
       }
     }
+    const searchTerm = typeof request.search === "string" ? request.search.trim() : "";
+    if (searchTerm) {
+      queryParams.set("search", searchTerm);
+      if (request.searchFields && request.searchFields.length > 0) {
+        queryParams.set("searchFields", request.searchFields.join(","));
+      }
+    }
     const baseUrl = this.baseUrl.replace(/\/$/, "");
     const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
     const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
@@ -2506,38 +2798,14 @@ var ObjectStackAdapter = class {
       const isEmpty = Array.isArray(params.$filter) ? params.$filter.length === 0 : typeof params.$filter === "object" && Object.keys(params.$filter).length === 0;
       if (!isEmpty) {
         if (Array.isArray(params.$filter)) {
-          const isObjectForm = params.$filter.length > 0 && typeof params.$filter[0] === "object" && !Array.isArray(params.$filter[0]) && params.$filter[0].field !== void 0;
-          if (isObjectForm) {
-            const tuples = params.$filter.map((entry) => objectFilterEntryToAST(entry)).filter((t) => t !== null);
-            if (tuples.length === 0) {
-            } else if (tuples.length === 1) {
-              options.filters = tuples[0];
-            } else {
-              options.filters = ["and", ...tuples];
-            }
-          } else {
-            options.filters = params.$filter;
-          }
+          options.filters = translateFilterArray(params.$filter);
         } else {
           options.filters = convertFiltersToAST(params.$filter);
         }
       }
     }
-    if (params.$orderby) {
-      if (Array.isArray(params.$orderby)) {
-        options.sort = params.$orderby.map((item) => {
-          if (typeof item === "string") return item;
-          const field = item.field;
-          const order = item.order || "asc";
-          return order === "desc" ? `-${field}` : field;
-        });
-      } else {
-        const sortArray = Object.entries(params.$orderby).map(([field, order]) => {
-          return order === "desc" ? `-${field}` : field;
-        });
-        options.sort = sortArray;
-      }
-    }
+    const sort = serializeOrderBy(params.$orderby);
+    if (sort) options.sort = sort;
     if (params.$skip !== void 0) {
       options.skip = params.$skip;
     }
@@ -3041,6 +3309,7 @@ var ObjectStackAdapter = class {
     }
     try {
       const measureName = params.function === "count" ? "count" : `${params.field}_${params.function}`;
+      const valueKey = this.aggregateValueKey(params);
       const payload = {
         cube: resource,
         measures: [measureName],
@@ -3055,30 +3324,62 @@ var ObjectStackAdapter = class {
       const measureMissing = rawRows.length > 0 && rawRows.every((row) => {
         if (row == null) return true;
         if (measureName in row && row[measureName] != null) return false;
-        if (params.field in row && row[params.field] != null) return false;
+        if (valueKey in row && row[valueKey] != null) return false;
         return true;
       });
       if (measureMissing) {
-        const result = await this.find(resource, params.filter ? { $filter: params.filter } : void 0);
-        const records = result.data || [];
-        if (records.length === 0) return [];
-        return this.aggregateClientSide(records, params);
+        return await this.aggregateViaFind(resource, params);
       }
       return rawRows.map((row) => {
         const mapped = { ...row };
-        if (measureName !== params.field && measureName in mapped) {
-          mapped[params.field] = mapped[measureName];
+        if (measureName !== valueKey && measureName in mapped) {
+          mapped[valueKey] = mapped[measureName];
           delete mapped[measureName];
         }
         return mapped;
       });
-    } catch {
-      const result = await this.find(resource, params.filter ? { $filter: params.filter } : void 0);
-      const records = result.data || [];
-      if (records.length === 0) return [];
-      return this.aggregateClientSide(records, params);
+    } catch (e) {
+      const failure = classifyAnalyticsFailure(e);
+      if (failure.kind === "rejected") {
+        throw new AnalyticsQueryRejectedError(failure.message, failure.code);
+      }
+      if (failure.kind === "not-installed") {
+        this.warnAnalyticsCapabilityOnce(failure.message);
+      }
+      return await this.aggregateViaFind(resource, params);
     }
   }
+  /**
+   * Client-side aggregation over a server-scoped `find()` — the fallback used
+   * whenever the analytics endpoint cannot answer (capability absent, network
+   * failure, or a result whose measure came back missing).
+   *
+   * Forwarding `params.filter` is load-bearing: without it the fallback
+   * aggregates the whole table while the caller believes it applied a filter,
+   * which is the "KPI silently sums everything" failure this adapter has
+   * guarded against since the widget filter was threaded through.
+   */
+  async aggregateViaFind(resource, params) {
+    const result = await this.find(
+      resource,
+      params.filter ? { $filter: params.filter } : void 0
+    );
+    const records = result.data || [];
+    if (records.length === 0) return [];
+    return this.aggregateClientSide(records, params);
+  }
+  /**
+   * Say "the analytics capability isn't installed" ONCE per adapter, not once
+   * per widget: a dashboard fans out one aggregate() per KPI, and N identical
+   * console lines read like N different failures.
+   */
+  warnAnalyticsCapabilityOnce(detail) {
+    if (this.analyticsCapabilityWarned) return;
+    this.analyticsCapabilityWarned = true;
+    console.warn(
+      "[OBJECTSTACKDataSource] analytics capability unavailable \u2014 aggregating client-side from a scoped find(). Numbers stay correct but the semantic layer (cubes, joins, server-side rollups) is off. Install @objectstack/service-analytics to enable it." + (detail ? ` Server said: ${detail}` : "")
+    );
+  }
   /**
    * Run a semantic-layer `dataset` (ADR-0021) and return chart-ready rows.
    *
@@ -3117,6 +3418,9 @@ var ObjectStackAdapter = class {
         detail = errBody?.message || errBody?.error || JSON.stringify(errBody);
       } catch {
       }
+      if (res.status === 501 || res.status === 404) {
+        throw new AnalyticsNotInstalledError("POST /analytics/dataset/query", detail || void 0);
+      }
       throw new Error(`Dataset query failed: ${res.status} ${res.statusText}${detail ? ` \u2014 ${detail}` : ""}`);
     }
     const payload = await res.json();
@@ -3130,8 +3434,18 @@ var ObjectStackAdapter = class {
     return { rows, fields, object, dimensionFields, drillRawRows, totals };
   }
   /** Client-side aggregation fallback */
+  /**
+   * The result column an object-bound `aggregate` projects its value under
+   * (framework#3701, `chartAggregateValueKey` in `@objectstack/spec/ui`): the
+   * raw `field` name — no `sum_`-style decoration, unlike a dataset measure —
+   * or the literal `count` when a count names no field.
+   */
+  aggregateValueKey(params) {
+    return params.field || params.function || "count";
+  }
   aggregateClientSide(records, params) {
     const { field, function: aggFn, groupBy } = params;
+    const valueKey = this.aggregateValueKey(params);
     const groups = {};
     for (const record of records) {
       const key = String(record[groupBy] ?? "Unknown");
@@ -3139,7 +3453,7 @@ var ObjectStackAdapter = class {
       groups[key].push(record);
     }
     return Object.entries(groups).map(([key, group]) => {
-      const values = group.map((r) => Number(r[field]) || 0);
+      const values = field ? group.map((r) => Number(r[field]) || 0) : [];
       let result;
       switch (aggFn) {
         case "count":
@@ -3159,7 +3473,7 @@ var ObjectStackAdapter = class {
           result = values.reduce((a, b) => a + b, 0);
           break;
       }
-      return { [groupBy]: key, [field]: result };
+      return { [groupBy]: key, [valueKey]: result };
     });
   }
   /**
@@ -3361,12 +3675,16 @@ function createObjectStackAdapter(config) {
   return new ObjectStackAdapter(config);
 }
 export {
+  AnalyticsNotInstalledError,
+  AnalyticsQueryRejectedError,
   AuthenticationError,
   BulkOperationError,
   CloudOperations,
   ConcurrentUpdateError,
   ConnectionError,
+  FILTER_OPERATOR_ALIASES,
   IntegrationManager,
+  MalformedFilterError,
   MetadataClient,
   MetadataNotFoundError,
   ObjectStackAdapter,
@@ -3374,6 +3692,7 @@ export {
   SecurityManager,
   ValidationError,
   calculateAutoLayout,
+  classifyAnalyticsFailure,
   clearSharedDiscoveryCache,
   createDefaultCanvasConfig,
   createErrorFromResponse,
@@ -3382,11 +3701,14 @@ export {
   generateContractManifest,
   getSharedDiscovery,
   is404Error,
+  isAnalyticsNotInstalledError,
   isConcurrentUpdateError,
   isErrorType,
+  isMalformedFilterError,
   isObjectStackError,
   normaliseClientError,
   readTransactionalBatchCapability,
+  serializeOrderBy,
   snapToGrid,
   validatePluginContract
 };