@object-ui/data-objectstack 16.1.0 → 17.1.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult, MutationEvent, BatchTransactionOperation, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, GlobalSearchResult, DataSourceMutationEvent, BatchTransactionOperation, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
 export { FileUploadResult } from '@object-ui/types';
 
 /**
@@ -1174,6 +1174,64 @@ declare function calculateAutoLayout(items: Array<{
     y: number;
 }>;
 
+/**
+ * Map human-readable filter operator names produced by SDUI view configs
+ * (e.g. `lead.view.ts`) to the canonical operator symbols expected by the
+ * ObjectStack server's filter AST. Unknown operators fall through unchanged
+ * so existing AST-style entries keep working.
+ *
+ * Every VALUE here must be a member of the spec's `VALID_AST_OPERATORS`
+ * (`@objectstack/spec/data`) — that set gates `isFilterAST()`, and a filter it
+ * rejects is not converted, not validated, and then silently DROPPED by
+ * driver-sql (objectstack#3948). Pinned by `filter-operator-ast-parity.test.ts`.
+ *
+ * Exported for that test. @internal
+ */
+declare const FILTER_OPERATOR_ALIASES: Record<string, string>;
+/**
+ * A filter entry this adapter cannot translate into an AST tuple.
+ *
+ * Thrown rather than skipped. Dropping one entry out of an `and` WIDENS the
+ * result set, and dropping the last one emits no `filter=` at all — every row,
+ * no error, from a query that asked for a subset. That is the same silent
+ * over-fetch the server-side drivers stopped doing in objectstack#3948, and
+ * skipping it here just moves it one layer up.
+ *
+ * Carries the code and status the data API uses for its own version of this
+ * refusal (objectstack#4121) so a failed list renders "this view's filter is
+ * malformed" rather than "check your connection" (#3066).
+ */
+declare class MalformedFilterError extends Error {
+    readonly code = "INVALID_FILTER";
+    readonly httpStatus = 400;
+    readonly entry: unknown;
+    readonly index: number;
+    constructor(entry: unknown, index: number);
+}
+/** Detect the malformed-filter refusal, whether raised here or by the server. */
+declare function isMalformedFilterError(error: unknown): boolean;
+/**
+ * Serialize a `$orderby` to the server's `sort` shorthand
+ * (`field,-other_field`), for every shape `QueryParams['$orderby']` declares.
+ *
+ * The type declares four — `string`, `string[]`, `SortNode[]`,
+ * `Record<field, direction>` — and the two `find()` routes each open-coded a
+ * fold that handled three of them. The missing one was the bare string, and it
+ * did not degrade quietly: `Object.entries('name asc')` enumerates a string's
+ * character indices, so the request went out as `sort=0,1,2,3,4,5,6,7`. Against
+ * a server that rejects an unreadable sort rather than ignoring it
+ * (objectstack#4226), that is a `400 INVALID_SORT` and an empty list — so a
+ * standalone `ObjectGrid` with a `sort` in its metadata, which is exactly the
+ * shape it builds (`ObjectGrid.tsx`: `` `${field} ${order}` ``), failed to load
+ * at all.
+ *
+ * One serializer for both routes, for the reason the filter path already has
+ * one: two copies of a fold can only agree by inspection, and these two did not.
+ *
+ * Returns `undefined` when nothing is sortable, so callers skip the parameter
+ * entirely rather than sending an empty one.
+ */
+declare function serializeOrderBy(orderby: QueryParams['$orderby']): string | undefined;
 /**
  * Fetch the server `discovery` document once per (baseUrl) and reuse the
  * resulting Promise. Used by `ObjectStackAdapter.connect()` (and any caller
@@ -1212,6 +1270,73 @@ declare function readTransactionalBatchCapability(discovery: unknown): boolean |
  * tripping on the property-name mismatch.
  */
 declare function is404Error(error: unknown): boolean;
+/**
+ * Thrown when the deployment has no analytics capability installed
+ * (framework#3891 / #4019).
+ *
+ * The framework retired its degraded in-kernel analytics fallback — it dropped
+ * the caller's RLS/tenant scope and ignored the contract filter, so it answered
+ * 200 with over-broad numbers. `@objectstack/service-analytics` is now the
+ * domain's only implementation, and a deployment without it answers:
+ *
+ *   - `POST /api/v1/analytics/query` → **404** (the routes aren't even mounted);
+ *   - `POST /api/v1/analytics/dataset/query` → **501 NOT_IMPLEMENTED**.
+ *
+ * Neither is a bug to report as a stack trace: it is a deployment that hasn't
+ * installed the capability. This error carries a message a UI can show as-is.
+ */
+declare class AnalyticsNotInstalledError extends Error {
+    readonly code = "ANALYTICS_NOT_INSTALLED";
+    /** The surface that was unavailable, for the message a host renders. */
+    readonly surface: string;
+    constructor(surface: string, detail?: string);
+}
+/** True when `error` is an {@link AnalyticsNotInstalledError} (or its wire twin). */
+declare function isAnalyticsNotInstalledError(error: unknown): boolean;
+/**
+ * Thrown when the server REJECTED the analytics query body (HTTP 400 —
+ * `VALIDATION_FAILED` since framework#4010 validates `/analytics/query` at the
+ * entry against the canonical bare `AnalyticsQuery` shape).
+ *
+ * Distinct from {@link AnalyticsNotInstalledError} on purpose: this one is a
+ * defect in what WE sent, so it must never be answered with the client-side
+ * fallback. Numbers produced by a different code path would look plausible and
+ * bury the contract violation — the misdirection framework#3878 documented.
+ */
+declare class AnalyticsQueryRejectedError extends Error {
+    readonly code = "ANALYTICS_QUERY_REJECTED";
+    /** The server's own error code (e.g. `VALIDATION_FAILED`), when it sent one. */
+    readonly serverCode?: string;
+    constructor(detail?: string, serverCode?: string);
+}
+/**
+ * Classify a FAILED analytics call so the caller knows whether to degrade or
+ * to surface the failure.
+ *
+ * `@objectstack/client`'s fetch wrapper throws on a non-2xx, decorating the
+ * error with the semantic `code` string and the numeric `httpStatus` (the
+ * ADR-0112 / framework#3842 shape this repo already reads elsewhere). Two
+ * outcomes must NOT be conflated:
+ *
+ *   - **`not-installed`** — the deployment has no analytics service. Since
+ *     framework#3891 retired the degraded in-kernel shim, that is a 404 (the
+ *     routes aren't mounted at all, framework#4019) or a 501 `NOT_IMPLEMENTED`
+ *     (REST's dataset route with no service behind it). Degrading to a
+ *     client-side aggregate over a scoped `find()` is CORRECT here.
+ *   - **`rejected`** — the server refused OUR body (400 `VALIDATION_FAILED`;
+ *     framework#4010 validates `/analytics/query` at the entry). Degrading
+ *     would answer our own contract violation with plausible numbers from a
+ *     different code path and bury it — the misdirection framework#3878
+ *     documented. It must be surfaced.
+ *
+ * Anything else (5xx, network) is `unknown`: degrade, but silently — it is a
+ * transient failure, not a deployment that is missing a capability.
+ */
+declare function classifyAnalyticsFailure(error: unknown): {
+    kind: 'not-installed' | 'rejected' | 'unknown';
+    code?: string;
+    message?: string;
+};
 /**
  * Thrown by `update()` / `delete()` when the server returns
  * `409 CONCURRENT_UPDATE` — i.e. the record was modified by someone else
@@ -1248,10 +1373,15 @@ declare class ConcurrentUpdateError extends Error {
  */
 declare function isConcurrentUpdateError(error: unknown): error is ConcurrentUpdateError;
 /**
- * Convert any error thrown by the upstream client into a typed
- * `ConcurrentUpdateError` when it represents a 409 CONCURRENT_UPDATE.
- * Returns the original error untouched otherwise. Callers can simply
- * `throw normaliseClientError(err)` from their catch blocks.
+ * Convert any error thrown by the upstream client into a typed error when we
+ * recognise its shape. Returns the original error untouched otherwise, so
+ * callers can simply `throw normaliseClientError(err)` from their catch blocks.
+ *
+ * Two shapes are recognised:
+ *   - `409` + `CONCURRENT_UPDATE` → {@link ConcurrentUpdateError};
+ *   - `400` + `VALIDATION_FAILED` → {@link ValidationError}, carrying the
+ *     server's per-field entries so a form can mark the offending inputs
+ *     instead of showing one undirected toast.
  */
 declare function normaliseClientError(error: unknown): unknown;
 /**
@@ -1284,6 +1414,33 @@ type ConnectionStateListener = (event: ConnectionStateEvent) => void;
  * Event listener type for batch operation progress
  */
 type BatchProgressListener = (event: BatchProgressEvent) => void;
+/**
+ * One server-reported write-strip: caller-supplied fields the backend LEGALLY
+ * removed from a write before persisting (a non-system caller cannot seed a
+ * `readonly` field, a `readonlyWhen` predicate locked it, etc.). Mirrors the
+ * framework `DroppedFieldsEvent` (spec `DroppedFieldsEventSchema`) structurally
+ * so we don't pin a client type version — `reason` is kept as a widened string
+ * for forward-compatibility with reasons added server-side.
+ */
+interface DroppedFieldsEvent {
+    object: string;
+    fields: string[];
+    reason: string;
+}
+/**
+ * Emitted after a create/update whose response carried `droppedFields`
+ * (framework #3431/#3455). The write SUCCEEDED — this is a warning that some
+ * supplied fields never landed, so the UI can tell the user rather than let it
+ * pass silently. Subscribe via {@link ObjectStackAdapter.onWriteWarning}.
+ */
+interface WriteWarningEvent {
+    operation: 'create' | 'update';
+    resource: string;
+    id?: string | number;
+    droppedFields: DroppedFieldsEvent[];
+}
+/** Event listener type for write-warning (dropped-fields) events. */
+type WriteWarningListener = (event: WriteWarningEvent) => void;
 
 /**
  * ObjectStack Data Source Adapter
@@ -1328,12 +1485,15 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private reconnectAttempts;
     private baseUrl;
     private token?;
+    /** One "analytics capability is missing" console line per adapter, not per widget. */
+    private analyticsCapabilityWarned;
     private fetchImpl;
     private inflightFinds;
     private missingResources;
     private batchUnsupported;
     private atomicBatchCapability;
     private mutationListeners;
+    private writeWarningListeners;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -1384,6 +1544,26 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Converts OData-style params to ObjectStack query options.
      */
     find(resource: string, params?: QueryParams): Promise<QueryResult<T>>;
+    /**
+     * 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.
+     */
+    searchAll(query: string, options?: {
+        limit?: number;
+        objects?: string[];
+    }): Promise<GlobalSearchResult>;
     /**
      * Find a single record by ID.
      */
@@ -1402,7 +1582,38 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * mutation (e.g. inline-edit "Save All", which writes through `update` and
      * must repaint the list without a manual reload).
      */
-    onMutation(callback: (event: MutationEvent<T>) => void): () => void;
+    onMutation(callback: (event: DataSourceMutationEvent<T>) => void): () => void;
+    /**
+     * Notify all write-warning subscribers. Isolated like {@link emitMutation}: a
+     * throwing listener must not break the write or starve the others.
+     */
+    private emitWriteWarning;
+    /**
+     * 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.
+     */
+    private notifyDroppedFields;
+    /**
+     * 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.
+     */
+    private notifyBatchDroppedFields;
+    /**
+     * 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: WriteWarningListener): () => void;
     create(resource: string, data: Partial<T>): Promise<T>;
     /**
      * Update an existing record.
@@ -1498,7 +1709,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     /** Mark the endpoint unsupported (warn once) and serve via emulation. */
     private fallbackToEmulation;
     /**
-     * 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
@@ -1776,6 +1987,23 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * is not available.
      */
     aggregate(resource: string, params: any): Promise<any[]>;
+    /**
+     * 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.
+     */
+    private aggregateViaFind;
+    /**
+     * 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.
+     */
+    private warnAnalyticsCapabilityOnce;
     /**
      * Run a semantic-layer `dataset` (ADR-0021) and return chart-ready rows.
      *
@@ -1836,6 +2064,13 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         }>;
     }>;
     /** 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.
+     */
+    private aggregateValueKey;
     private aggregateClientSide;
     /**
      * Get multiple metadata items from ObjectStack.
@@ -1938,4 +2173,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, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, type MetadataAuditEntry, type MetadataAuditResponse, MetadataClient, type MetadataClientConfig, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, type MetadataValidationIssue, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isConcurrentUpdateError, isErrorType, isObjectStackError, normaliseClientError, readTransactionalBatchCapability, snapToGrid, validatePluginContract };
+export { AnalyticsNotInstalledError, AnalyticsQueryRejectedError, type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type DroppedFieldsEvent, type EmailIntegrationConfig, FILTER_OPERATOR_ALIASES, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MalformedFilterError, type MetadataAuditEntry, type MetadataAuditResponse, MetadataClient, type MetadataClientConfig, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, type MetadataValidationIssue, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, type WriteWarningEvent, type WriteWarningListener, calculateAutoLayout, classifyAnalyticsFailure, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isAnalyticsNotInstalledError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isObjectStackError, normaliseClientError, readTransactionalBatchCapability, serializeOrderBy, snapToGrid, validatePluginContract };