@object-ui/data-objectstack 11.2.0 → 11.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult, 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.
      */
@@ -1443,6 +1506,17 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * to findData({ object, query: req.query }) which processes `populate`.
      */
     private rawFindWithPopulate;
+    /**
+     * Synchronously download a server-streamed export (csv / json / xlsx).
+     *
+     * Hits `GET /api/v1/data/:object/export`, which streams matching rows in the
+     * requested format, formats values for readability (lookup → name, select →
+     * label, boolean → 是/否, dates formatted) and enforces permissions. The
+     * filter / sort are translated the same way as `rawFindWithPopulate` so the
+     * exported file mirrors the active list view. Returns the file as a Blob;
+     * the caller triggers the browser download.
+     */
+    exportDownload(resource: string, request?: ExportDownloadRequest): Promise<Blob>;
     /**
      * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
      * Maps OData-style conventions to ObjectStack conventions.
@@ -1770,4 +1844,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.js

@@ -537,6 +537,7 @@ function createObjectStackUserStateAdapter(options) {
     }
   } = options;
   let cachedRowId = null;
+  let saveChain = Promise.resolve();
   const findExisting = async () => {
     const params = {
       $filter: {
@@ -567,6 +568,42 @@ function createObjectStackUserStateAdapter(options) {
     }
     return [];
   };
+  const upsert = async (items) => {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (cachedRowId !== null) {
+      try {
+        await dataSource.update(resource, cachedRowId, { value: items, updated_at: now });
+        return;
+      } catch (updateError) {
+        cachedRowId = null;
+        onError("save", updateError);
+      }
+    }
+    const existing = await findExisting();
+    if (existing && existing.id !== void 0 && existing.id !== null) {
+      cachedRowId = existing.id;
+      await dataSource.update(resource, existing.id, { value: items, updated_at: now });
+      return;
+    }
+    try {
+      const created = await dataSource.create(resource, {
+        user_id: userId,
+        key,
+        value: items,
+        updated_at: now
+      });
+      const newId = created?.id;
+      if (newId !== void 0 && newId !== null) cachedRowId = newId;
+    } catch (createError) {
+      const recovered = await findExisting();
+      if (recovered && recovered.id !== void 0 && recovered.id !== null) {
+        cachedRowId = recovered.id;
+        await dataSource.update(resource, recovered.id, { value: items, updated_at: now });
+        return;
+      }
+      throw createError;
+    }
+  };
   return {
     async load() {
       try {
@@ -583,40 +620,11 @@ function createObjectStackUserStateAdapter(options) {
       }
     },
     async save(items) {
-      try {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        if (cachedRowId !== null) {
-          try {
-            await dataSource.update(resource, cachedRowId, {
-              value: items,
-              updated_at: now
-            });
-            return;
-          } catch (updateError) {
-            cachedRowId = null;
-            onError("save", updateError);
-          }
-        }
-        const existing = await findExisting();
-        if (existing && existing.id !== void 0 && existing.id !== null) {
-          cachedRowId = existing.id;
-          await dataSource.update(resource, existing.id, {
-            value: items,
-            updated_at: now
-          });
-          return;
-        }
-        const created = await dataSource.create(resource, {
-          user_id: userId,
-          key,
-          value: items,
-          updated_at: now
-        });
-        const newId = created?.id;
-        if (newId !== void 0 && newId !== null) cachedRowId = newId;
-      } catch (error) {
+      const run = saveChain.then(() => upsert(items)).catch((error) => {
         onError("save", error);
-      }
+      });
+      saveChain = run;
+      return run;
     }
   };
 }
@@ -752,13 +760,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 {
@@ -1468,6 +1480,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 ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
@@ -1676,9 +1693,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;
   }
   /**
@@ -1701,6 +1744,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);
@@ -1721,6 +1765,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);
@@ -1745,15 +1792,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);
       }
@@ -1766,7 +1817,7 @@ var ObjectStackAdapter = class {
       } catch {
       }
     }
-    return succeeded;
+    return emitBulk(succeeded);
   }
   /**
    * Single-call bulk delete. Mirrors the bulkUpdate contract: prefers
@@ -1779,15 +1830,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);
       }
@@ -1800,7 +1855,7 @@ var ObjectStackAdapter = class {
       } catch {
       }
     }
-    return succeeded;
+    return emitBulk(succeeded);
   }
   /**
    * Bulk operations with optimized batch processing and error handling.
@@ -1960,6 +2015,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.
    */
@@ -2057,6 +2263,53 @@ var ObjectStackAdapter = class {
     }
     return body;
   }
+  /**
+   * Synchronously download a server-streamed export (csv / json / xlsx).
+   *
+   * Hits `GET /api/v1/data/:object/export`, which streams matching rows in the
+   * requested format, formats values for readability (lookup → name, select →
+   * label, boolean → 是/否, dates formatted) and enforces permissions. The
+   * filter / sort are translated the same way as `rawFindWithPopulate` so the
+   * exported file mirrors the active list view. Returns the file as a Blob;
+   * the caller triggers the browser download.
+   */
+  async exportDownload(resource, request = {}) {
+    const queryParams = new URLSearchParams();
+    const format = request.format === "xlsx" ? "xlsx" : request.format === "json" ? "json" : "csv";
+    queryParams.set("format", format);
+    if (request.fields && request.fields.length > 0) {
+      queryParams.set("fields", request.fields.join(","));
+    }
+    if (request.limit && request.limit > 0) {
+      queryParams.set("limit", String(request.limit));
+    }
+    if (request.includeHeaders === false) {
+      queryParams.set("header", "false");
+    }
+    if (request.sort && request.sort.length > 0) {
+      const orderby = request.sort.filter((s) => s && s.field).map((s) => `${s.field}:${s.direction === "desc" ? "desc" : "asc"}`).join(",");
+      if (orderby) queryParams.set("orderby", orderby);
+    }
+    if (request.filter !== void 0 && request.filter !== null) {
+      const translated = translateFilterToAST(request.filter);
+      if (translated !== void 0) {
+        queryParams.set("filter", JSON.stringify(translated));
+      }
+    }
+    const baseUrl = this.baseUrl.replace(/\/$/, "");
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
+    const url = `${baseUrl}${dataPath}/${encodeURIComponent(resource)}/export?${queryParams.toString()}`;
+    const headers = { ...this.getAuthHeaders() };
+    const res = await this.fetchImpl(url, { method: "GET", headers, credentials: "include" });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      err.status = res.status;
+      throw err;
+    }
+    return await res.blob();
+  }
   /**
    * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
    * Maps OData-style conventions to ObjectStack conventions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "11.2.0",
+  "version": "11.4.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,9 +22,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^11.0.0",
-    "@object-ui/core": "11.2.0",
-    "@object-ui/types": "11.2.0"
+    "@objectstack/client": "^11.5.0",
+    "@object-ui/core": "11.4.0",
+    "@object-ui/types": "11.4.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",