@object-ui/data-objectstack 4.0.7 → 4.0.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @object-ui/data-objectstack
 
+## 4.0.9
+
+### Patch Changes
+
+- @object-ui/types@4.0.9
+- @object-ui/core@4.0.9
+
+## 4.0.8
+
+### Patch Changes
+
+- @object-ui/types@4.0.8
+- @object-ui/core@4.0.8
+
 ## 4.0.7
 
 ### Patch Changes

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   createObjectStackAdapter: () => createObjectStackAdapter,
   generateContractManifest: () => generateContractManifest,
   getSharedDiscovery: () => getSharedDiscovery,
+  is404Error: () => is404Error,
   isErrorType: () => isErrorType,
   isObjectStackError: () => isObjectStackError,
   snapToGrid: () => snapToGrid,
@@ -895,6 +896,44 @@ async function getSharedDiscovery(baseUrl, fetcher) {
 function clearSharedDiscoveryCache() {
   discoveryCache.clear();
 }
+function is404Error(error) {
+  if (!error || typeof error !== "object") return false;
+  const err = error;
+  if (err.httpStatus === 404 || err.status === 404 || err.statusCode === 404) {
+    return true;
+  }
+  const code = typeof err.code === "string" ? err.code : "";
+  return code === "object_not_found" || code === "record_not_found";
+}
+function createQuietHttpLogger() {
+  const isExpected404 = (meta) => {
+    if (!meta || typeof meta !== "object") return false;
+    if (meta.status === 404 || meta.statusCode === 404) return true;
+    const errBody = meta.error;
+    if (errBody && typeof errBody === "object") {
+      const code = errBody.code;
+      if (code === "object_not_found" || code === "record_not_found") return true;
+    }
+    return false;
+  };
+  const logger = {
+    debug: (message, meta) => console.debug(message, meta ?? ""),
+    info: (message, meta) => console.info(message, meta ?? ""),
+    warn: (message, meta) => console.warn(message, meta ?? ""),
+    error: (message, error, meta) => {
+      if (isExpected404(meta)) {
+        console.debug(`[ObjectStack] ${message} (suppressed expected 404)`, meta);
+        return;
+      }
+      console.error(message, error ?? "", meta ?? "");
+    },
+    fatal: (message, error, meta) => console.error(message, error ?? "", meta ?? ""),
+    log: (message, ...args) => console.log(message, ...args),
+    child: () => logger,
+    withTrace: () => logger
+  };
+  return logger;
+}
 function stableStringify(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
@@ -923,7 +962,7 @@ var ObjectStackAdapter = class {
     // multiple sibling components requesting the same dataset on first paint)
     // into a single network round trip.
     __publicField(this, "inflightFinds", /* @__PURE__ */ new Map());
-    this.client = new import_client.ObjectStackClient(config);
+    this.client = new import_client.ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
     this.maxReconnectAttempts = config.maxReconnectAttempts ?? 3;
@@ -1074,11 +1113,12 @@ var ObjectStackAdapter = class {
       return this.normalizeQueryResult(result, params);
     })();
     this.inflightFinds.set(key, promise);
-    promise.finally(() => {
+    const cleanup = () => {
       if (this.inflightFinds.get(key) === promise) {
         this.inflightFinds.delete(key);
       }
-    });
+    };
+    promise.then(cleanup, cleanup);
     return promise;
   }
   /**
@@ -1101,7 +1141,7 @@ var ObjectStackAdapter = class {
         const records = resultObj.records || resultObj.value || [];
         return records[0] || null;
       } catch (error) {
-        if (error?.status === 404) {
+        if (is404Error(error)) {
           return null;
         }
       }
@@ -1110,7 +1150,7 @@ var ObjectStackAdapter = class {
       const result = await this.client.data.get(resource, String(id));
       return result.record;
     } catch (error) {
-      if (error?.status === 404) {
+      if (is404Error(error)) {
         return null;
       }
       throw error;
@@ -1434,7 +1474,7 @@ var ObjectStackAdapter = class {
       return schema;
     } catch (error) {
       const errorObj = error;
-      if (errorObj?.status === 404 || errorObj?.statusCode === 404) {
+      if (is404Error(errorObj)) {
         throw new MetadataNotFoundError(objectName, { originalError: error });
       }
       if (error instanceof ObjectStackError) {
@@ -1466,6 +1506,43 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Batch-fetch all persisted view overrides for an object.
+   *
+   * Per-view runtime overrides (density, column widths, sort, …) are
+   * stored in the metadata registry under key `<objectName>/<viewName>`.
+   * Loading them per-view fires N HTTP GETs that return 404 for views
+   * the user has never customized — generates console noise on every
+   * page load. This batch method performs a single
+   * `GET /api/v1/meta/<objectName>` (returns `{type, items}`) and
+   * returns a `{viewName: override}` map. Returns an empty map if the
+   * server doesn't expose the listing or returns no items.
+   *
+   * Result is cached identically to {@link getView}; saving a view via
+   * {@link updateViewConfig} invalidates the cache.
+   *
+   * @param objectName - Object name (e.g. 'lead')
+   * @returns Map keyed by view name with the persisted override config
+   */
+  async listViewOverrides(objectName) {
+    await this.connect();
+    try {
+      const cacheKey = `view-overrides:${objectName}`;
+      return await this.metadataCache.get(cacheKey, async () => {
+        const result = await this.client.meta.getItems(objectName);
+        const items = Array.isArray(result?.items) ? result.items : [];
+        const out = {};
+        for (const it of items) {
+          if (!it || typeof it !== "object") continue;
+          const key = it.name ?? it.id ?? it._name;
+          if (typeof key === "string" && key) out[key] = it;
+        }
+        return out;
+      });
+    } catch {
+      return {};
+    }
+  }
   /**
    * Get a view definition for an object.
    * Attempts to fetch from the server metadata API.
@@ -1481,7 +1558,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `view:${objectName}:${viewId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem(objectName, `views/${viewId}`);
+        const result = await this.client.meta.getItem(objectName, viewId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -1489,6 +1566,40 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Persist a view definition for an object.
+   *
+   * Symmetric counterpart to {@link getView}: writes the view to the
+   * server metadata store via `client.meta.saveItem`, then invalidates
+   * the matching cache entry so the next {@link getView} reflects the
+   * new payload. Returns the persisted item when the server echoes it,
+   * otherwise undefined.
+   *
+   * Used by ObjectView for "live" toolbar persistence (density,
+   * column widths, sort, etc.) and by the View Config Panel for
+   * explicit saves.
+   *
+   * @param objectName - Object name (e.g. 'lead')
+   * @param viewId - View identifier (e.g. 'all_leads')
+   * @param config - Full view definition to persist
+   */
+  async updateViewConfig(objectName, viewId, config) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.saveItem(
+        objectName,
+        viewId,
+        config
+      );
+      const cacheKey = `view:${objectName}:${viewId}`;
+      this.metadataCache.invalidate?.(cacheKey);
+      this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+      if (result && result.item) return result.item;
+      return result ?? void 0;
+    } catch (err) {
+      throw err;
+    }
+  }
   /**
    * Get an application definition by name or ID.
    * Attempts to fetch from the server metadata API.
@@ -1529,6 +1640,34 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Update (upsert) a dashboard definition.
+   *
+   * Dashboards are control-plane metadata, not data records. Persist via
+   * `client.meta.saveItem('dashboard', name, schema)` which routes to
+   * `PUT /api/v1/meta/dashboard/:name`. After save, invalidates the
+   * relevant metadata cache entry so the next dashboard read reflects
+   * the new payload.
+   *
+   * @param dashboardName - Dashboard identifier (e.g. 'crm_overview_dashboard')
+   * @param schema - Full dashboard schema (widgets, layout, etc.)
+   */
+  async updateDashboard(dashboardName, schema) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.saveItem(
+        "dashboard",
+        dashboardName,
+        schema
+      );
+      this.metadataCache.invalidate?.("dashboards");
+      this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
+      if (result && result.item) return result.item;
+      return result ?? void 0;
+    } catch (err) {
+      throw err;
+    }
+  }
   /**
    * Perform server-side aggregation via the ObjectStack analytics API.
    * Uses `this.client.analytics.query()` from @objectstack/client to leverage
@@ -1547,7 +1686,7 @@ var ObjectStackAdapter = class {
         dimensions: params.groupBy && params.groupBy !== "_all" ? [params.groupBy] : []
       };
       if (params.filter) {
-        payload.filters = params.filter;
+        payload.where = params.filter;
       }
       const data = await this.client.analytics.query(payload);
       const rawRows = Array.isArray(data) ? data : data?.rows && Array.isArray(data.rows) ? data.rows : data?.data && Array.isArray(data.data) ? data.data : data?.data?.rows && Array.isArray(data.data.rows) ? data.data.rows : data?.results && Array.isArray(data.results) ? data.results : [];
@@ -1558,7 +1697,7 @@ var ObjectStackAdapter = class {
         return true;
       });
       if (measureMissing) {
-        const result = await this.find(resource);
+        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);
@@ -1572,7 +1711,7 @@ var ObjectStackAdapter = class {
         return mapped;
       });
     } catch {
-      const result = await this.find(resource);
+      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);
@@ -1771,6 +1910,7 @@ function createObjectStackAdapter(config) {
   createObjectStackAdapter,
   generateContractManifest,
   getSharedDiscovery,
+  is404Error,
   isErrorType,
   isObjectStackError,
   snapToGrid,

package/dist/index.d.cts

@@ -648,6 +648,16 @@ declare function calculateAutoLayout(items: Array<{
 declare function getSharedDiscovery(baseUrl: string, fetcher: () => Promise<unknown>): Promise<unknown>;
 /** Test/dev helper to drop the cache (e.g. on logout or origin change). */
 declare function clearSharedDiscoveryCache(): void;
+/**
+ * Detect "missing resource" errors regardless of where they originate.
+ *
+ * The ObjectStack client decorates thrown errors with `httpStatus` (and a
+ * machine-readable `code` such as `object_not_found`/`record_not_found`),
+ * while raw `fetch()` callers may surface `status` or `statusCode`. Treat
+ * any of these as a 404 so callers can degrade gracefully instead of
+ * tripping on the property-name mismatch.
+ */
+declare function is404Error(error: unknown): boolean;
 /**
  * Connection state for monitoring
  */
@@ -838,6 +848,25 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to discovery data, or null if not connected
      */
     getDiscovery(): Promise<unknown | null>;
+    /**
+     * Batch-fetch all persisted view overrides for an object.
+     *
+     * Per-view runtime overrides (density, column widths, sort, …) are
+     * stored in the metadata registry under key `<objectName>/<viewName>`.
+     * Loading them per-view fires N HTTP GETs that return 404 for views
+     * the user has never customized — generates console noise on every
+     * page load. This batch method performs a single
+     * `GET /api/v1/meta/<objectName>` (returns `{type, items}`) and
+     * returns a `{viewName: override}` map. Returns an empty map if the
+     * server doesn't expose the listing or returns no items.
+     *
+     * Result is cached identically to {@link getView}; saving a view via
+     * {@link updateViewConfig} invalidates the cache.
+     *
+     * @param objectName - Object name (e.g. 'lead')
+     * @returns Map keyed by view name with the persisted override config
+     */
+    listViewOverrides(objectName: string): Promise<Record<string, any>>;
     /**
      * Get a view definition for an object.
      * Attempts to fetch from the server metadata API.
@@ -849,6 +878,24 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to the view definition or null
      */
     getView(objectName: string, viewId: string): Promise<unknown | null>;
+    /**
+     * Persist a view definition for an object.
+     *
+     * Symmetric counterpart to {@link getView}: writes the view to the
+     * server metadata store via `client.meta.saveItem`, then invalidates
+     * the matching cache entry so the next {@link getView} reflects the
+     * new payload. Returns the persisted item when the server echoes it,
+     * otherwise undefined.
+     *
+     * Used by ObjectView for "live" toolbar persistence (density,
+     * column widths, sort, etc.) and by the View Config Panel for
+     * explicit saves.
+     *
+     * @param objectName - Object name (e.g. 'lead')
+     * @param viewId - View identifier (e.g. 'all_leads')
+     * @param config - Full view definition to persist
+     */
+    updateViewConfig(objectName: string, viewId: string, config: Record<string, any>): Promise<Record<string, any> | void>;
     /**
      * Get an application definition by name or ID.
      * Attempts to fetch from the server metadata API.
@@ -865,6 +912,19 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Returns null if the server doesn't support page metadata.
      */
     getPage(pageId: string): Promise<unknown | null>;
+    /**
+     * Update (upsert) a dashboard definition.
+     *
+     * Dashboards are control-plane metadata, not data records. Persist via
+     * `client.meta.saveItem('dashboard', name, schema)` which routes to
+     * `PUT /api/v1/meta/dashboard/:name`. After save, invalidates the
+     * relevant metadata cache entry so the next dashboard read reflects
+     * the new payload.
+     *
+     * @param dashboardName - Dashboard identifier (e.g. 'crm_overview_dashboard')
+     * @param schema - Full dashboard schema (widgets, layout, etc.)
+     */
+    updateDashboard(dashboardName: string, schema: Record<string, any>): Promise<Record<string, any> | void>;
     /**
      * Perform server-side aggregation via the ObjectStack analytics API.
      * Uses `this.client.analytics.query()` from @objectstack/client to leverage
@@ -966,4 +1026,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, generateContractManifest, getSharedDiscovery, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, generateContractManifest, getSharedDiscovery, is404Error, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };

package/dist/index.d.ts

@@ -648,6 +648,16 @@ declare function calculateAutoLayout(items: Array<{
 declare function getSharedDiscovery(baseUrl: string, fetcher: () => Promise<unknown>): Promise<unknown>;
 /** Test/dev helper to drop the cache (e.g. on logout or origin change). */
 declare function clearSharedDiscoveryCache(): void;
+/**
+ * Detect "missing resource" errors regardless of where they originate.
+ *
+ * The ObjectStack client decorates thrown errors with `httpStatus` (and a
+ * machine-readable `code` such as `object_not_found`/`record_not_found`),
+ * while raw `fetch()` callers may surface `status` or `statusCode`. Treat
+ * any of these as a 404 so callers can degrade gracefully instead of
+ * tripping on the property-name mismatch.
+ */
+declare function is404Error(error: unknown): boolean;
 /**
  * Connection state for monitoring
  */
@@ -838,6 +848,25 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to discovery data, or null if not connected
      */
     getDiscovery(): Promise<unknown | null>;
+    /**
+     * Batch-fetch all persisted view overrides for an object.
+     *
+     * Per-view runtime overrides (density, column widths, sort, …) are
+     * stored in the metadata registry under key `<objectName>/<viewName>`.
+     * Loading them per-view fires N HTTP GETs that return 404 for views
+     * the user has never customized — generates console noise on every
+     * page load. This batch method performs a single
+     * `GET /api/v1/meta/<objectName>` (returns `{type, items}`) and
+     * returns a `{viewName: override}` map. Returns an empty map if the
+     * server doesn't expose the listing or returns no items.
+     *
+     * Result is cached identically to {@link getView}; saving a view via
+     * {@link updateViewConfig} invalidates the cache.
+     *
+     * @param objectName - Object name (e.g. 'lead')
+     * @returns Map keyed by view name with the persisted override config
+     */
+    listViewOverrides(objectName: string): Promise<Record<string, any>>;
     /**
      * Get a view definition for an object.
      * Attempts to fetch from the server metadata API.
@@ -849,6 +878,24 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to the view definition or null
      */
     getView(objectName: string, viewId: string): Promise<unknown | null>;
+    /**
+     * Persist a view definition for an object.
+     *
+     * Symmetric counterpart to {@link getView}: writes the view to the
+     * server metadata store via `client.meta.saveItem`, then invalidates
+     * the matching cache entry so the next {@link getView} reflects the
+     * new payload. Returns the persisted item when the server echoes it,
+     * otherwise undefined.
+     *
+     * Used by ObjectView for "live" toolbar persistence (density,
+     * column widths, sort, etc.) and by the View Config Panel for
+     * explicit saves.
+     *
+     * @param objectName - Object name (e.g. 'lead')
+     * @param viewId - View identifier (e.g. 'all_leads')
+     * @param config - Full view definition to persist
+     */
+    updateViewConfig(objectName: string, viewId: string, config: Record<string, any>): Promise<Record<string, any> | void>;
     /**
      * Get an application definition by name or ID.
      * Attempts to fetch from the server metadata API.
@@ -865,6 +912,19 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Returns null if the server doesn't support page metadata.
      */
     getPage(pageId: string): Promise<unknown | null>;
+    /**
+     * Update (upsert) a dashboard definition.
+     *
+     * Dashboards are control-plane metadata, not data records. Persist via
+     * `client.meta.saveItem('dashboard', name, schema)` which routes to
+     * `PUT /api/v1/meta/dashboard/:name`. After save, invalidates the
+     * relevant metadata cache entry so the next dashboard read reflects
+     * the new payload.
+     *
+     * @param dashboardName - Dashboard identifier (e.g. 'crm_overview_dashboard')
+     * @param schema - Full dashboard schema (widgets, layout, etc.)
+     */
+    updateDashboard(dashboardName: string, schema: Record<string, any>): Promise<Record<string, any> | void>;
     /**
      * Perform server-side aggregation via the ObjectStack analytics API.
      * Uses `this.client.analytics.query()` from @objectstack/client to leverage
@@ -966,4 +1026,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, generateContractManifest, getSharedDiscovery, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, generateContractManifest, getSharedDiscovery, is404Error, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };

package/dist/index.js

@@ -853,6 +853,44 @@ async function getSharedDiscovery(baseUrl, fetcher) {
 function clearSharedDiscoveryCache() {
   discoveryCache.clear();
 }
+function is404Error(error) {
+  if (!error || typeof error !== "object") return false;
+  const err = error;
+  if (err.httpStatus === 404 || err.status === 404 || err.statusCode === 404) {
+    return true;
+  }
+  const code = typeof err.code === "string" ? err.code : "";
+  return code === "object_not_found" || code === "record_not_found";
+}
+function createQuietHttpLogger() {
+  const isExpected404 = (meta) => {
+    if (!meta || typeof meta !== "object") return false;
+    if (meta.status === 404 || meta.statusCode === 404) return true;
+    const errBody = meta.error;
+    if (errBody && typeof errBody === "object") {
+      const code = errBody.code;
+      if (code === "object_not_found" || code === "record_not_found") return true;
+    }
+    return false;
+  };
+  const logger = {
+    debug: (message, meta) => console.debug(message, meta ?? ""),
+    info: (message, meta) => console.info(message, meta ?? ""),
+    warn: (message, meta) => console.warn(message, meta ?? ""),
+    error: (message, error, meta) => {
+      if (isExpected404(meta)) {
+        console.debug(`[ObjectStack] ${message} (suppressed expected 404)`, meta);
+        return;
+      }
+      console.error(message, error ?? "", meta ?? "");
+    },
+    fatal: (message, error, meta) => console.error(message, error ?? "", meta ?? ""),
+    log: (message, ...args) => console.log(message, ...args),
+    child: () => logger,
+    withTrace: () => logger
+  };
+  return logger;
+}
 function stableStringify(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
@@ -881,7 +919,7 @@ var ObjectStackAdapter = class {
     // multiple sibling components requesting the same dataset on first paint)
     // into a single network round trip.
     __publicField(this, "inflightFinds", /* @__PURE__ */ new Map());
-    this.client = new ObjectStackClient(config);
+    this.client = new ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
     this.maxReconnectAttempts = config.maxReconnectAttempts ?? 3;
@@ -1032,11 +1070,12 @@ var ObjectStackAdapter = class {
       return this.normalizeQueryResult(result, params);
     })();
     this.inflightFinds.set(key, promise);
-    promise.finally(() => {
+    const cleanup = () => {
       if (this.inflightFinds.get(key) === promise) {
         this.inflightFinds.delete(key);
       }
-    });
+    };
+    promise.then(cleanup, cleanup);
     return promise;
   }
   /**
@@ -1059,7 +1098,7 @@ var ObjectStackAdapter = class {
         const records = resultObj.records || resultObj.value || [];
         return records[0] || null;
       } catch (error) {
-        if (error?.status === 404) {
+        if (is404Error(error)) {
           return null;
         }
       }
@@ -1068,7 +1107,7 @@ var ObjectStackAdapter = class {
       const result = await this.client.data.get(resource, String(id));
       return result.record;
     } catch (error) {
-      if (error?.status === 404) {
+      if (is404Error(error)) {
         return null;
       }
       throw error;
@@ -1392,7 +1431,7 @@ var ObjectStackAdapter = class {
       return schema;
     } catch (error) {
       const errorObj = error;
-      if (errorObj?.status === 404 || errorObj?.statusCode === 404) {
+      if (is404Error(errorObj)) {
         throw new MetadataNotFoundError(objectName, { originalError: error });
       }
       if (error instanceof ObjectStackError) {
@@ -1424,6 +1463,43 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Batch-fetch all persisted view overrides for an object.
+   *
+   * Per-view runtime overrides (density, column widths, sort, …) are
+   * stored in the metadata registry under key `<objectName>/<viewName>`.
+   * Loading them per-view fires N HTTP GETs that return 404 for views
+   * the user has never customized — generates console noise on every
+   * page load. This batch method performs a single
+   * `GET /api/v1/meta/<objectName>` (returns `{type, items}`) and
+   * returns a `{viewName: override}` map. Returns an empty map if the
+   * server doesn't expose the listing or returns no items.
+   *
+   * Result is cached identically to {@link getView}; saving a view via
+   * {@link updateViewConfig} invalidates the cache.
+   *
+   * @param objectName - Object name (e.g. 'lead')
+   * @returns Map keyed by view name with the persisted override config
+   */
+  async listViewOverrides(objectName) {
+    await this.connect();
+    try {
+      const cacheKey = `view-overrides:${objectName}`;
+      return await this.metadataCache.get(cacheKey, async () => {
+        const result = await this.client.meta.getItems(objectName);
+        const items = Array.isArray(result?.items) ? result.items : [];
+        const out = {};
+        for (const it of items) {
+          if (!it || typeof it !== "object") continue;
+          const key = it.name ?? it.id ?? it._name;
+          if (typeof key === "string" && key) out[key] = it;
+        }
+        return out;
+      });
+    } catch {
+      return {};
+    }
+  }
   /**
    * Get a view definition for an object.
    * Attempts to fetch from the server metadata API.
@@ -1439,7 +1515,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `view:${objectName}:${viewId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem(objectName, `views/${viewId}`);
+        const result = await this.client.meta.getItem(objectName, viewId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -1447,6 +1523,40 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Persist a view definition for an object.
+   *
+   * Symmetric counterpart to {@link getView}: writes the view to the
+   * server metadata store via `client.meta.saveItem`, then invalidates
+   * the matching cache entry so the next {@link getView} reflects the
+   * new payload. Returns the persisted item when the server echoes it,
+   * otherwise undefined.
+   *
+   * Used by ObjectView for "live" toolbar persistence (density,
+   * column widths, sort, etc.) and by the View Config Panel for
+   * explicit saves.
+   *
+   * @param objectName - Object name (e.g. 'lead')
+   * @param viewId - View identifier (e.g. 'all_leads')
+   * @param config - Full view definition to persist
+   */
+  async updateViewConfig(objectName, viewId, config) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.saveItem(
+        objectName,
+        viewId,
+        config
+      );
+      const cacheKey = `view:${objectName}:${viewId}`;
+      this.metadataCache.invalidate?.(cacheKey);
+      this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+      if (result && result.item) return result.item;
+      return result ?? void 0;
+    } catch (err) {
+      throw err;
+    }
+  }
   /**
    * Get an application definition by name or ID.
    * Attempts to fetch from the server metadata API.
@@ -1487,6 +1597,34 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Update (upsert) a dashboard definition.
+   *
+   * Dashboards are control-plane metadata, not data records. Persist via
+   * `client.meta.saveItem('dashboard', name, schema)` which routes to
+   * `PUT /api/v1/meta/dashboard/:name`. After save, invalidates the
+   * relevant metadata cache entry so the next dashboard read reflects
+   * the new payload.
+   *
+   * @param dashboardName - Dashboard identifier (e.g. 'crm_overview_dashboard')
+   * @param schema - Full dashboard schema (widgets, layout, etc.)
+   */
+  async updateDashboard(dashboardName, schema) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.saveItem(
+        "dashboard",
+        dashboardName,
+        schema
+      );
+      this.metadataCache.invalidate?.("dashboards");
+      this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
+      if (result && result.item) return result.item;
+      return result ?? void 0;
+    } catch (err) {
+      throw err;
+    }
+  }
   /**
    * Perform server-side aggregation via the ObjectStack analytics API.
    * Uses `this.client.analytics.query()` from @objectstack/client to leverage
@@ -1505,7 +1643,7 @@ var ObjectStackAdapter = class {
         dimensions: params.groupBy && params.groupBy !== "_all" ? [params.groupBy] : []
       };
       if (params.filter) {
-        payload.filters = params.filter;
+        payload.where = params.filter;
       }
       const data = await this.client.analytics.query(payload);
       const rawRows = Array.isArray(data) ? data : data?.rows && Array.isArray(data.rows) ? data.rows : data?.data && Array.isArray(data.data) ? data.data : data?.data?.rows && Array.isArray(data.data.rows) ? data.data.rows : data?.results && Array.isArray(data.results) ? data.results : [];
@@ -1516,7 +1654,7 @@ var ObjectStackAdapter = class {
         return true;
       });
       if (measureMissing) {
-        const result = await this.find(resource);
+        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);
@@ -1530,7 +1668,7 @@ var ObjectStackAdapter = class {
         return mapped;
       });
     } catch {
-      const result = await this.find(resource);
+      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);
@@ -1728,6 +1866,7 @@ export {
   createObjectStackAdapter,
   generateContractManifest,
   getSharedDiscovery,
+  is404Error,
   isErrorType,
   isObjectStackError,
   snapToGrid,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "4.0.7",
+  "version": "4.0.9",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,14 +22,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^4.0.4",
-    "@object-ui/core": "4.0.7",
-    "@object-ui/types": "4.0.7"
+    "@objectstack/client": "^4.0.5",
+    "@object-ui/core": "4.0.9",
+    "@object-ui/types": "4.0.9"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.6"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -110,6 +110,70 @@ export function clearSharedDiscoveryCache(): void {
   discoveryCache.clear();
 }
 
+/**
+ * Detect "missing resource" errors regardless of where they originate.
+ *
+ * The ObjectStack client decorates thrown errors with `httpStatus` (and a
+ * machine-readable `code` such as `object_not_found`/`record_not_found`),
+ * while raw `fetch()` callers may surface `status` or `statusCode`. Treat
+ * any of these as a 404 so callers can degrade gracefully instead of
+ * tripping on the property-name mismatch.
+ */
+export function is404Error(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const err = error as Record<string, unknown>;
+  if (err.httpStatus === 404 || err.status === 404 || err.statusCode === 404) {
+    return true;
+  }
+  const code = typeof err.code === 'string' ? err.code : '';
+  return code === 'object_not_found' || code === 'record_not_found';
+}
+
+/**
+ * Build a Logger compatible with @objectstack/client that demotes expected
+ * 404 noise to console.debug. The client logs every non-2xx response with
+ * `logger.error("HTTP request failed", undefined, { status, error })`, but
+ * 404s on optional collections (sys_presence, sys_activity, …) are part of
+ * normal degraded operation when those plugins aren't installed on the
+ * server — they should not surface as errors in the browser DevTools.
+ *
+ * Returned object is loosely typed because the spec's Logger interface lives
+ * in a transitive package; using `any` keeps us decoupled.
+ */
+function createQuietHttpLogger(): any {
+  const isExpected404 = (meta?: Record<string, any>): boolean => {
+    if (!meta || typeof meta !== 'object') return false;
+    if (meta.status === 404 || meta.statusCode === 404) return true;
+    const errBody = meta.error;
+    if (errBody && typeof errBody === 'object') {
+      const code = (errBody as Record<string, unknown>).code;
+      if (code === 'object_not_found' || code === 'record_not_found') return true;
+    }
+    return false;
+  };
+  const logger: any = {
+    debug: (message: string, meta?: Record<string, any>) =>
+      console.debug(message, meta ?? ''),
+    info: (message: string, meta?: Record<string, any>) =>
+      console.info(message, meta ?? ''),
+    warn: (message: string, meta?: Record<string, any>) =>
+      console.warn(message, meta ?? ''),
+    error: (message: string, error?: Error, meta?: Record<string, any>) => {
+      if (isExpected404(meta)) {
+        console.debug(`[ObjectStack] ${message} (suppressed expected 404)`, meta);
+        return;
+      }
+      console.error(message, error ?? '', meta ?? '');
+    },
+    fatal: (message: string, error?: Error, meta?: Record<string, any>) =>
+      console.error(message, error ?? '', meta ?? ''),
+    log: (message: string, ...args: any[]) => console.log(message, ...args),
+    child: () => logger,
+    withTrace: () => logger,
+  };
+  return logger;
+}
+
 /**
  * Connection state for monitoring
  */
@@ -224,7 +288,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     maxReconnectAttempts?: number;
     reconnectDelay?: number;
   }) {
-    this.client = new ObjectStackClient(config);
+    // Inject a quiet logger that demotes expected 404s ("HTTP request failed"
+    // from probing optional collections like sys_presence/sys_activity) to
+    // debug() so they don't pollute the browser console. Other log levels are
+    // forwarded to the standard console.
+    this.client = new ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
     this.maxReconnectAttempts = config.maxReconnectAttempts ?? 3;
@@ -426,13 +494,19 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     })();
 
     this.inflightFinds.set(key, promise);
-    promise.finally(() => {
+    // Use `.then(cleanup, cleanup)` instead of `.finally(cleanup)`. `.finally`
+    // returns a new chained promise that re-raises the rejection, and because
+    // we don't return that chain, Node/browsers see it as an unhandled
+    // rejection — flooding DevTools when callers handle the original `promise`
+    // via `.catch()` (e.g. AppHeader probing optional sys_presence/sys_activity).
+    const cleanup = () => {
       // Only clear if the entry still points at this promise; a later call
       // that started after settle may have already replaced it.
       if (this.inflightFinds.get(key) === promise) {
         this.inflightFinds.delete(key);
       }
-    });
+    };
+    promise.then(cleanup, cleanup);
     return promise;
   }
 
@@ -461,7 +535,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         const records = resultObj.records || resultObj.value || [];
         return records[0] || null;
       } catch (error: unknown) {
-        if ((error as Record<string, unknown>)?.status === 404) {
+        if (is404Error(error)) {
           return null;
         }
         // Fall through to direct GET without $expand — some servers don't
@@ -475,7 +549,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       return result.record;
     } catch (error: unknown) {
       // If record not found, return null instead of throwing
-      if ((error as Record<string, unknown>)?.status === 404) {
+      if (is404Error(error)) {
         return null;
       }
       throw error;
@@ -908,7 +982,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     } catch (error: unknown) {
       // Check if it's a 404 error
       const errorObj = error as Record<string, unknown>;
-      if (errorObj?.status === 404 || errorObj?.statusCode === 404) {
+      if (is404Error(errorObj)) {
         throw new MetadataNotFoundError(objectName, { originalError: error });
       }
       
@@ -952,6 +1026,45 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Batch-fetch all persisted view overrides for an object.
+   *
+   * Per-view runtime overrides (density, column widths, sort, …) are
+   * stored in the metadata registry under key `<objectName>/<viewName>`.
+   * Loading them per-view fires N HTTP GETs that return 404 for views
+   * the user has never customized — generates console noise on every
+   * page load. This batch method performs a single
+   * `GET /api/v1/meta/<objectName>` (returns `{type, items}`) and
+   * returns a `{viewName: override}` map. Returns an empty map if the
+   * server doesn't expose the listing or returns no items.
+   *
+   * Result is cached identically to {@link getView}; saving a view via
+   * {@link updateViewConfig} invalidates the cache.
+   *
+   * @param objectName - Object name (e.g. 'lead')
+   * @returns Map keyed by view name with the persisted override config
+   */
+  async listViewOverrides(objectName: string): Promise<Record<string, any>> {
+    await this.connect();
+
+    try {
+      const cacheKey = `view-overrides:${objectName}`;
+      return await this.metadataCache.get(cacheKey, async () => {
+        const result: any = await this.client.meta.getItems(objectName);
+        const items: any[] = Array.isArray(result?.items) ? result.items : [];
+        const out: Record<string, any> = {};
+        for (const it of items) {
+          if (!it || typeof it !== 'object') continue;
+          const key = it.name ?? it.id ?? it._name;
+          if (typeof key === 'string' && key) out[key] = it;
+        }
+        return out;
+      });
+    } catch {
+      return {};
+    }
+  }
+
   /**
    * Get a view definition for an object.
    * Attempts to fetch from the server metadata API.
@@ -969,7 +1082,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       const cacheKey = `view:${objectName}:${viewId}`;
       return await this.metadataCache.get(cacheKey, async () => {
         // Try meta.getItem for view metadata
-        const result: any = await this.client.meta.getItem(objectName, `views/${viewId}`);
+        const result: any = await this.client.meta.getItem(objectName, viewId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -979,6 +1092,50 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Persist a view definition for an object.
+   *
+   * Symmetric counterpart to {@link getView}: writes the view to the
+   * server metadata store via `client.meta.saveItem`, then invalidates
+   * the matching cache entry so the next {@link getView} reflects the
+   * new payload. Returns the persisted item when the server echoes it,
+   * otherwise undefined.
+   *
+   * Used by ObjectView for "live" toolbar persistence (density,
+   * column widths, sort, etc.) and by the View Config Panel for
+   * explicit saves.
+   *
+   * @param objectName - Object name (e.g. 'lead')
+   * @param viewId - View identifier (e.g. 'all_leads')
+   * @param config - Full view definition to persist
+   */
+  async updateViewConfig(
+    objectName: string,
+    viewId: string,
+    config: Record<string, any>
+  ): Promise<Record<string, any> | void> {
+    await this.connect();
+    try {
+      const result: any = await this.client.meta.saveItem(
+        objectName,
+        viewId,
+        config
+      );
+      // Invalidate cached read so next getView reflects the change
+      const cacheKey = `view:${objectName}:${viewId}`;
+      this.metadataCache.invalidate?.(cacheKey);
+      // Also invalidate the batch override map so listViewOverrides re-fetches
+      this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+      if (result && result.item) return result.item;
+      return result ?? undefined;
+    } catch (err) {
+      // Surface the error so the caller can decide whether to toast/log;
+      // we don't swallow it here because persistence failures are
+      // operationally meaningful (unlike read fallbacks).
+      throw err;
+    }
+  }
+
   /**
    * Get an application definition by name or ID.
    * Attempts to fetch from the server metadata API.
@@ -1025,6 +1182,40 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Update (upsert) a dashboard definition.
+   *
+   * Dashboards are control-plane metadata, not data records. Persist via
+   * `client.meta.saveItem('dashboard', name, schema)` which routes to
+   * `PUT /api/v1/meta/dashboard/:name`. After save, invalidates the
+   * relevant metadata cache entry so the next dashboard read reflects
+   * the new payload.
+   *
+   * @param dashboardName - Dashboard identifier (e.g. 'crm_overview_dashboard')
+   * @param schema - Full dashboard schema (widgets, layout, etc.)
+   */
+  async updateDashboard(
+    dashboardName: string,
+    schema: Record<string, any>
+  ): Promise<Record<string, any> | void> {
+    await this.connect();
+    try {
+      const result: any = await this.client.meta.saveItem(
+        'dashboard',
+        dashboardName,
+        schema
+      );
+      // Invalidate dashboards list and any cached dashboard read so the
+      // next render reflects the change.
+      this.metadataCache.invalidate?.('dashboards');
+      this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
+      if (result && result.item) return result.item;
+      return result ?? undefined;
+    } catch (err) {
+      throw err;
+    }
+  }
+
   /**
    * Perform server-side aggregation via the ObjectStack analytics API.
    * Uses `this.client.analytics.query()` from @objectstack/client to leverage
@@ -1051,7 +1242,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         dimensions: params.groupBy && params.groupBy !== '_all' ? [params.groupBy] : [],
       };
       if (params.filter) {
-        payload.filters = params.filter;
+        // Dashboard widgets emit MongoDB-style FilterCondition (per
+        // spec/ui/dashboard.zod.ts). Send via the canonical `where`
+        // field of the analytics endpoint, matching the unified Query
+        // DSL (spec/data/query.zod.ts).
+        payload.where = params.filter;
       }
 
       const data = await this.client.analytics.query(payload);
@@ -1074,7 +1269,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         return true;
       });
       if (measureMissing) {
-        const result = await this.find(resource as any);
+        const result = await this.find(resource as any, params.filter ? { $filter: params.filter } as any : undefined);
         const records = result.data || [];
         if (records.length === 0) return [];
         return this.aggregateClientSide(records, params);
@@ -1094,8 +1289,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       });
     } catch {
       // If the analytics endpoint is not available, fall back to
-      // find() + client-side aggregation
-      const result = await this.find(resource as any);
+      // find() + client-side aggregation. Crucially, forward the same
+      // filter so the fallback aggregates over the SAME row set the
+      // server-side analytics query would have — otherwise the KPI
+      // silently sums the whole table and lies to the user.
+      const result = await this.find(resource as any, params.filter ? { $filter: params.filter } as any : undefined);
       const records = result.data || [];
       if (records.length === 0) return [];