@object-ui/data-objectstack 11.3.0 → 11.5.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @object-ui/data-objectstack
 
+## 11.5.0
+
+### Minor Changes
+
+- 1072701: Import wizard: use registered server-side import mappings (framework #2611). When an object has `mapping` metadata artifacts targeting it, the wizard shows a "Saved mapping" selector; picking one hands rename + transforms + write semantics to the server (the artifact is authoritative), replaces the manual column table with a read-only summary of the mapping, and submits `mappingName` over source-header rows (mutually exclusive with the inline column rename). `ImportRequestOptions` gains `mappingName`; the objectstack adapter gains `listImportMappings(objectName)` (feature-detected — the selector simply doesn't appear when unsupported). New `grid.import.*` strings added across all locales.
+
+### Patch Changes
+
+- Updated dependencies [9255686]
+- Updated dependencies [1072701]
+  - @object-ui/types@11.5.0
+  - @object-ui/core@11.5.0
+
+## 11.4.0
+
+### Patch Changes
+
+- c0164ad: fix(studio): surface spec-validation failures on the field at save/publish
+
+  When a Studio metadata draft failed spec validation, the designer got a single
+  opaque banner (and, on a partial publish, a false "published!" toast) — the
+  server was already returning field-anchored issues, but the client threw them
+  away. Two problems, both fixed:
+
+  - **`parseError` (data-objectstack)** read `String(body.error)`, which yields
+    `"[object Object]"` for the dispatcher's object-shaped error, and ignored the
+    validation `issues`. It now reads the message from either shape (string or
+    `{ message }`) and exposes `MetadataError.issues`, accepting all live server
+    shapes — top-level `body.issues` (REST server) and `error.details.issues`
+    (HTTP dispatcher).
+
+  - **Studio save/publish (app-shell)** now render those issues **field-anchored**.
+    A new `formatMetadataError` helper turns a caught error into one line per
+    offending field (`• fields.amount.type — Invalid option: …`); the save banners
+    render it with `whitespace-pre-line`. `doPublish` no longer claims success when
+    the response carries `data.failed[]` — it lists which drafts failed and why
+    (the server returns 200 with the failures buried, so the UI used to swallow
+    them). `formatPublishFailures` formats those per-draft.
+
+  Verified end-to-end against a live backend: an invalid object draft returns 422
+  with field-anchored issues, and the Studio banner shows
+  `• fields.amount.type — Invalid option: expected one of "text"|…` instead of a
+  generic message. Unit-tested: `parseError` on the dispatcher shape, and the
+  `formatMetadataError` / `formatPublishFailures` helpers.
+
+- Updated dependencies [8bf6295]
+- Updated dependencies [1948c5b]
+- Updated dependencies [c38d107]
+  - @object-ui/types@11.4.0
+  - @object-ui/core@11.4.0
+
 ## 11.3.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -808,13 +808,17 @@ async function parseError(res) {
   } catch {
     body = await res.text().catch(() => void 0);
   }
-  const message = (body && typeof body === "object" && "error" in body ? String(body.error) : void 0) ?? `Metadata request failed: ${res.status} ${res.statusText}`;
-  const err = new Error(message);
+  const bodyObj = body && typeof body === "object" ? body : void 0;
+  const errNode = bodyObj?.error;
+  const message = (errNode && typeof errNode === "object" ? errNode.message : errNode) ?? bodyObj?.message ?? `Metadata request failed: ${res.status} ${res.statusText}`;
+  const err = new Error(String(message));
   err.status = res.status;
   err.body = body;
-  if (body && typeof body === "object" && "code" in body) {
-    err.code = String(body.code);
-  }
+  const details = errNode && typeof errNode === "object" ? errNode.details : void 0;
+  const issues = details?.issues ?? (errNode && typeof errNode === "object" ? errNode.issues : void 0) ?? bodyObj?.issues;
+  if (Array.isArray(issues)) err.issues = issues;
+  const code = details?.code ?? (errNode && typeof errNode === "object" ? errNode.code : void 0) ?? bodyObj?.code;
+  if (code != null) err.code = String(code);
   return err;
 }
 var MetadataClient = class _MetadataClient {
@@ -1524,6 +1528,11 @@ var ObjectStackAdapter = class {
     // so optional collections like sys_presence don't hammer the server with
     // failing requests on every record open / panel render.
     __publicField(this, "missingResources", /* @__PURE__ */ new Set());
+    // Subscribers registered via onMutation(). Emitted after each successful
+    // create/update/delete so data-bound views (ListView, ObjectView, kanban,
+    // 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());
     this.client = new import_client.ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
@@ -1732,9 +1741,35 @@ var ObjectStackAdapter = class {
   /**
    * Create a new record.
    */
+  /**
+   * Notify all mutation subscribers. A throwing listener must not break the
+   * mutation or starve the other subscribers, so each is isolated.
+   */
+  emitMutation(event) {
+    for (const listener of this.mutationListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn("ObjectStackAdapter: mutation listener error", err);
+      }
+    }
+  }
+  /**
+   * Subscribe to create/update/delete events on any resource. Returns an
+   * unsubscribe function. Data-bound views use this to auto-refresh after a
+   * mutation (e.g. inline-edit "Save All", which writes through `update` and
+   * must repaint the list without a manual reload).
+   */
+  onMutation(callback) {
+    this.mutationListeners.add(callback);
+    return () => {
+      this.mutationListeners.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;
   }
   /**
@@ -1757,6 +1792,7 @@ var ObjectStackAdapter = class {
         data,
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
+      this.emitMutation({ type: "update", resource, id, record: { ...result.record } });
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -1777,6 +1813,9 @@ var ObjectStackAdapter = class {
         String(id),
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
+      if (result.deleted) {
+        this.emitMutation({ type: "delete", resource, id });
+      }
       return result.deleted;
     } catch (err) {
       throw normaliseClientError(err);
@@ -1801,15 +1840,19 @@ var ObjectStackAdapter = class {
     await this.connect();
     if (!ids || ids.length === 0) return 0;
     const records = ids.map((id) => ({ id: String(id), data: patch }));
+    const emitBulk = (count) => {
+      if (count > 0) this.emitMutation({ type: "update", resource });
+      return count;
+    };
     const updateMany = this.client.data.updateMany;
     if (typeof updateMany === "function") {
       try {
         const res = await updateMany(resource, records, { continueOnError: true });
         if (res && typeof res === "object" && typeof res.succeeded === "number") {
-          return res.succeeded;
+          return emitBulk(res.succeeded);
         }
-        if (Array.isArray(res)) return res.length;
-        return ids.length;
+        if (Array.isArray(res)) return emitBulk(res.length);
+        return emitBulk(ids.length);
       } catch (err) {
         throw normaliseClientError(err);
       }
@@ -1822,7 +1865,7 @@ var ObjectStackAdapter = class {
       } catch {
       }
     }
-    return succeeded;
+    return emitBulk(succeeded);
   }
   /**
    * Single-call bulk delete. Mirrors the bulkUpdate contract: prefers
@@ -1835,15 +1878,19 @@ var ObjectStackAdapter = class {
     await this.connect();
     if (!ids || ids.length === 0) return 0;
     const strIds = ids.map((id) => String(id));
+    const emitBulk = (count) => {
+      if (count > 0) this.emitMutation({ type: "delete", resource });
+      return count;
+    };
     const deleteMany = this.client.data.deleteMany;
     if (typeof deleteMany === "function") {
       try {
         const res = await deleteMany(resource, strIds, { continueOnError: true });
         if (res && typeof res === "object" && typeof res.succeeded === "number") {
-          return res.succeeded;
+          return emitBulk(res.succeeded);
         }
-        if (Array.isArray(res)) return res.length;
-        return strIds.length;
+        if (Array.isArray(res)) return emitBulk(res.length);
+        return emitBulk(strIds.length);
       } catch (err) {
         throw normaliseClientError(err);
       }
@@ -1856,7 +1903,7 @@ var ObjectStackAdapter = class {
       } catch {
       }
     }
-    return succeeded;
+    return emitBulk(succeeded);
   }
   /**
    * Bulk operations with optimized batch processing and error handling.
@@ -2016,6 +2063,157 @@ var ObjectStackAdapter = class {
       );
     }
   }
+  /**
+   * Bulk-import raw spreadsheet rows in a single server round-trip via
+   * `POST /api/v1/data/:object/import`. The server performs all value coercion
+   * (booleans, numbers, dates→ISO, select label→code, lookup name→id) from the
+   * object's field metadata, so this method forwards the request verbatim and
+   * returns the aggregate + per-row result untouched.
+   *
+   * Requires `@objectstack/client` with `data.import` (server `/import` route).
+   * Callers should feature-detect (`typeof dataSource.importRecords`) and fall
+   * back to a per-row `create` loop when unavailable.
+   */
+  async importRecords(resource, request) {
+    await this.connect();
+    const importFn = this.client.data.import;
+    if (typeof importFn !== "function") {
+      throw new ObjectStackError(
+        "The connected @objectstack/client does not support data.import(). Upgrade the client, or import via a per-row create fallback.",
+        "UNSUPPORTED_OPERATION",
+        400
+      );
+    }
+    try {
+      const result = await importFn.call(this.client.data, resource, request);
+      return result;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+  /**
+   * Feature-detect the async import-job API on the connected client. Older
+   * clients/servers lack these routes; callers fall back to {@link importRecords}.
+   */
+  importJobApi() {
+    const d = this.client.data;
+    if (typeof d.createImportJob !== "function") return void 0;
+    return d;
+  }
+  /**
+   * Start an asynchronous import job — the large-file counterpart to
+   * {@link importRecords}. Posts the whole payload once; the server processes
+   * rows in the background. Requires an `@objectstack/client` new enough to
+   * expose `data.createImportJob` (server `/import/jobs` route). Callers should
+   * feature-detect (`typeof dataSource.createImportJob`) and fall back to the
+   * synchronous path when unavailable.
+   */
+  async createImportJob(resource, request) {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        "The connected @objectstack/client does not support async import jobs (data.createImportJob). Upgrade the client, or use the synchronous importRecords() path.",
+        "UNSUPPORTED_OPERATION",
+        400
+      );
+    }
+    try {
+      return await api.createImportJob.call(this.client.data, resource, request);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+  /** Poll an import job's progress. Requires {@link createImportJob} support. */
+  async getImportJobProgress(jobId) {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        "The connected @objectstack/client does not support async import jobs.",
+        "UNSUPPORTED_OPERATION",
+        400
+      );
+    }
+    try {
+      return await api.getImportJobProgress.call(this.client.data, jobId);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+  /** Fetch an import job's capped per-row results. */
+  async getImportJobResults(jobId) {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        "The connected @objectstack/client does not support async import jobs.",
+        "UNSUPPORTED_OPERATION",
+        400
+      );
+    }
+    try {
+      return await api.getImportJobResults.call(this.client.data, jobId);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+  /** List recent import jobs (history), newest first. */
+  async listImportJobs(options = {}) {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        "The connected @objectstack/client does not support async import jobs.",
+        "UNSUPPORTED_OPERATION",
+        400
+      );
+    }
+    try {
+      return await api.listImportJobs.call(this.client.data, options);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+  /** Cancel a pending/running import job (cooperative). */
+  async cancelImportJob(jobId) {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        "The connected @objectstack/client does not support async import jobs.",
+        "UNSUPPORTED_OPERATION",
+        400
+      );
+    }
+    try {
+      await api.cancelImportJob.call(this.client.data, jobId);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+  /**
+   * Logically roll back a finished import job — delete the records it created
+   * and restore the records it updated to their pre-import values. Requires an
+   * `@objectstack/client` new enough to expose `data.undoImportJob`, and a job
+   * the server captured an undo log for (see {@link ImportJobProgressInfo.undoable}).
+   */
+  async undoImportJob(jobId) {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api || typeof api.undoImportJob !== "function") {
+      throw new ObjectStackError(
+        "The connected @objectstack/client does not support undoing import jobs (data.undoImportJob).",
+        "UNSUPPORTED_OPERATION",
+        400
+      );
+    }
+    try {
+      return await api.undoImportJob.call(this.client.data, jobId);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
   /**
    * Normalize the result from data.find() or data.query() into a consistent QueryResult.
    */
@@ -2447,6 +2645,25 @@ var ObjectStackAdapter = class {
       return [];
     }
   }
+  /**
+   * List registered import `mapping` artifacts targeting a given object
+   * (framework #2611). Reads the `mapping` metadata kind via the overlay API
+   * and filters by `targetObject` client-side (the metadata index is
+   * name-only). Feeds the import wizard's "saved mapping" selector; a failure
+   * (older server without the `mapping` kind) degrades to an empty list, so
+   * the selector simply doesn't appear.
+   */
+  async listImportMappings(objectName) {
+    await this.connect();
+    try {
+      const result = await this.client.meta.getItems("mapping");
+      const items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
+      return items.filter((m) => m && m.targetObject === objectName);
+    } catch (err) {
+      console.warn("[OBJECTSTACKDataSource] listImportMappings failed:", err);
+      return [];
+    }
+  }
   /**
    * Create a new overlay view for an object. The view's `name` is the
    * stable identifier — must be unique within the project scope. Returns

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, MutationEvent, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
 export { FileUploadResult } from '@object-ui/types';
 
 /**
@@ -764,10 +764,19 @@ interface MetadataHistoryOptions {
     /** Limit the number of events returned. */
     limit?: number;
 }
+/** A single field-anchored spec-validation issue (server `error.details.issues`). */
+interface MetadataValidationIssue {
+    /** Dot-path to the offending field, e.g. `fields.amount.type` (`''` = root). */
+    path: string;
+    message: string;
+    code?: string;
+}
 interface MetadataError extends Error {
     status: number;
     code?: string;
     body?: unknown;
+    /** Structured spec-validation issues, when the failure was a validation error. */
+    issues?: MetadataValidationIssue[];
 }
 /**
  * MetadataClient — read/write protocol metadata via the framework REST API.
@@ -1302,6 +1311,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private fetchImpl;
     private inflightFinds;
     private missingResources;
+    private mutationListeners;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -1359,6 +1369,18 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     /**
      * Create a new record.
      */
+    /**
+     * Notify all mutation subscribers. A throwing listener must not break the
+     * mutation or starve the other subscribers, so each is isolated.
+     */
+    private emitMutation;
+    /**
+     * Subscribe to create/update/delete events on any resource. Returns an
+     * unsubscribe function. Data-bound views use this to auto-refresh after a
+     * 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;
     create(resource: string, data: Partial<T>): Promise<T>;
     /**
      * Update an existing record.
@@ -1432,6 +1454,47 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         results: any[];
     }>;
     bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
+    /**
+     * Bulk-import raw spreadsheet rows in a single server round-trip via
+     * `POST /api/v1/data/:object/import`. The server performs all value coercion
+     * (booleans, numbers, dates→ISO, select label→code, lookup name→id) from the
+     * object's field metadata, so this method forwards the request verbatim and
+     * returns the aggregate + per-row result untouched.
+     *
+     * Requires `@objectstack/client` with `data.import` (server `/import` route).
+     * Callers should feature-detect (`typeof dataSource.importRecords`) and fall
+     * back to a per-row `create` loop when unavailable.
+     */
+    importRecords(resource: string, request: ImportRequestOptions): Promise<ImportRecordsResult>;
+    /**
+     * Feature-detect the async import-job API on the connected client. Older
+     * clients/servers lack these routes; callers fall back to {@link importRecords}.
+     */
+    private importJobApi;
+    /**
+     * Start an asynchronous import job — the large-file counterpart to
+     * {@link importRecords}. Posts the whole payload once; the server processes
+     * rows in the background. Requires an `@objectstack/client` new enough to
+     * expose `data.createImportJob` (server `/import/jobs` route). Callers should
+     * feature-detect (`typeof dataSource.createImportJob`) and fall back to the
+     * synchronous path when unavailable.
+     */
+    createImportJob(resource: string, request: ImportRequestOptions): Promise<CreateImportJobResult>;
+    /** Poll an import job's progress. Requires {@link createImportJob} support. */
+    getImportJobProgress(jobId: string): Promise<ImportJobProgressInfo>;
+    /** Fetch an import job's capped per-row results. */
+    getImportJobResults(jobId: string): Promise<ImportJobResultsInfo>;
+    /** List recent import jobs (history), newest first. */
+    listImportJobs(options?: ListImportJobsOptions): Promise<ImportJobSummaryInfo[]>;
+    /** Cancel a pending/running import job (cooperative). */
+    cancelImportJob(jobId: string): Promise<void>;
+    /**
+     * Logically roll back a finished import job — delete the records it created
+     * and restore the records it updated to their pre-import values. Requires an
+     * `@objectstack/client` new enough to expose `data.undoImportJob`, and a job
+     * the server captured an undo log for (see {@link ImportJobProgressInfo.undoable}).
+     */
+    undoImportJob(jobId: string): Promise<ImportJobUndoResult>;
     /**
      * Normalize the result from data.find() or data.query() into a consistent QueryResult.
      */
@@ -1558,6 +1621,15 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * client-side because the metadata index is name-only, not field-typed.
      */
     listViews(objectName: string): Promise<any[]>;
+    /**
+     * List registered import `mapping` artifacts targeting a given object
+     * (framework #2611). Reads the `mapping` metadata kind via the overlay API
+     * and filters by `targetObject` client-side (the metadata index is
+     * name-only). Feeds the import wizard's "saved mapping" selector; a failure
+     * (older server without the `mapping` kind) degrades to an empty list, so
+     * the selector simply doesn't appear.
+     */
+    listImportMappings(objectName: string): Promise<any[]>;
     /**
      * Create a new overlay view for an object. The view's `name` is the
      * stable identifier — must be unique within the project scope. Returns
@@ -1781,4 +1853,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, 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, 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, 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, snapToGrid, validatePluginContract };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, MutationEvent, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
 export { FileUploadResult } from '@object-ui/types';
 
 /**
@@ -764,10 +764,19 @@ interface MetadataHistoryOptions {
     /** Limit the number of events returned. */
     limit?: number;
 }
+/** A single field-anchored spec-validation issue (server `error.details.issues`). */
+interface MetadataValidationIssue {
+    /** Dot-path to the offending field, e.g. `fields.amount.type` (`''` = root). */
+    path: string;
+    message: string;
+    code?: string;
+}
 interface MetadataError extends Error {
     status: number;
     code?: string;
     body?: unknown;
+    /** Structured spec-validation issues, when the failure was a validation error. */
+    issues?: MetadataValidationIssue[];
 }
 /**
  * MetadataClient — read/write protocol metadata via the framework REST API.
@@ -1302,6 +1311,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private fetchImpl;
     private inflightFinds;
     private missingResources;
+    private mutationListeners;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -1359,6 +1369,18 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     /**
      * Create a new record.
      */
+    /**
+     * Notify all mutation subscribers. A throwing listener must not break the
+     * mutation or starve the other subscribers, so each is isolated.
+     */
+    private emitMutation;
+    /**
+     * Subscribe to create/update/delete events on any resource. Returns an
+     * unsubscribe function. Data-bound views use this to auto-refresh after a
+     * 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;
     create(resource: string, data: Partial<T>): Promise<T>;
     /**
      * Update an existing record.
@@ -1432,6 +1454,47 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         results: any[];
     }>;
     bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
+    /**
+     * Bulk-import raw spreadsheet rows in a single server round-trip via
+     * `POST /api/v1/data/:object/import`. The server performs all value coercion
+     * (booleans, numbers, dates→ISO, select label→code, lookup name→id) from the
+     * object's field metadata, so this method forwards the request verbatim and
+     * returns the aggregate + per-row result untouched.
+     *
+     * Requires `@objectstack/client` with `data.import` (server `/import` route).
+     * Callers should feature-detect (`typeof dataSource.importRecords`) and fall
+     * back to a per-row `create` loop when unavailable.
+     */
+    importRecords(resource: string, request: ImportRequestOptions): Promise<ImportRecordsResult>;
+    /**
+     * Feature-detect the async import-job API on the connected client. Older
+     * clients/servers lack these routes; callers fall back to {@link importRecords}.
+     */
+    private importJobApi;
+    /**
+     * Start an asynchronous import job — the large-file counterpart to
+     * {@link importRecords}. Posts the whole payload once; the server processes
+     * rows in the background. Requires an `@objectstack/client` new enough to
+     * expose `data.createImportJob` (server `/import/jobs` route). Callers should
+     * feature-detect (`typeof dataSource.createImportJob`) and fall back to the
+     * synchronous path when unavailable.
+     */
+    createImportJob(resource: string, request: ImportRequestOptions): Promise<CreateImportJobResult>;
+    /** Poll an import job's progress. Requires {@link createImportJob} support. */
+    getImportJobProgress(jobId: string): Promise<ImportJobProgressInfo>;
+    /** Fetch an import job's capped per-row results. */
+    getImportJobResults(jobId: string): Promise<ImportJobResultsInfo>;
+    /** List recent import jobs (history), newest first. */
+    listImportJobs(options?: ListImportJobsOptions): Promise<ImportJobSummaryInfo[]>;
+    /** Cancel a pending/running import job (cooperative). */
+    cancelImportJob(jobId: string): Promise<void>;
+    /**
+     * Logically roll back a finished import job — delete the records it created
+     * and restore the records it updated to their pre-import values. Requires an
+     * `@objectstack/client` new enough to expose `data.undoImportJob`, and a job
+     * the server captured an undo log for (see {@link ImportJobProgressInfo.undoable}).
+     */
+    undoImportJob(jobId: string): Promise<ImportJobUndoResult>;
     /**
      * Normalize the result from data.find() or data.query() into a consistent QueryResult.
      */
@@ -1558,6 +1621,15 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * client-side because the metadata index is name-only, not field-typed.
      */
     listViews(objectName: string): Promise<any[]>;
+    /**
+     * List registered import `mapping` artifacts targeting a given object
+     * (framework #2611). Reads the `mapping` metadata kind via the overlay API
+     * and filters by `targetObject` client-side (the metadata index is
+     * name-only). Feeds the import wizard's "saved mapping" selector; a failure
+     * (older server without the `mapping` kind) degrades to an empty list, so
+     * the selector simply doesn't appear.
+     */
+    listImportMappings(objectName: string): Promise<any[]>;
     /**
      * Create a new overlay view for an object. The view's `name` is the
      * stable identifier — must be unique within the project scope. Returns
@@ -1781,4 +1853,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, 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, 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, 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, snapToGrid, validatePluginContract };