@object-ui/data-objectstack 11.2.0 → 11.4.0

package/src/exportDownload.test.ts

@@ -0,0 +1,93 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+
+/** Build an adapter whose fetch is a spy returning the given Response. */
+function makeDS(fetchImpl: any) {
+  const ds: any = new ObjectStackAdapter({ baseUrl: 'http://test.local', fetch: fetchImpl });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  return ds;
+}
+
+function csvResponse(body = 'ID,Name\n1,Acme') {
+  return new Response(body, { status: 200, headers: { 'Content-Type': 'text/csv' } });
+}
+
+describe('ObjectStackAdapter.exportDownload', () => {
+  it('GETs the /export route with format, fields, orderby, header and limit', async () => {
+    const fetchImpl = vi.fn(async () => csvResponse());
+    const ds = makeDS(fetchImpl);
+
+    const blob = await ds.exportDownload('task', {
+      format: 'xlsx',
+      fields: ['title', 'owner'],
+      sort: [{ field: 'title', direction: 'desc' }, { field: 'owner' }],
+      includeHeaders: false,
+      limit: 5000,
+    });
+
+    expect(blob).toBeInstanceOf(Blob);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchImpl.mock.calls[0];
+    const parsed = new URL(url);
+    expect(parsed.pathname).toBe('/api/v1/data/task/export');
+    expect(parsed.searchParams.get('format')).toBe('xlsx');
+    expect(parsed.searchParams.get('fields')).toBe('title,owner');
+    // direction defaults to asc when omitted.
+    expect(parsed.searchParams.get('orderby')).toBe('title:desc,owner:asc');
+    expect(parsed.searchParams.get('header')).toBe('false');
+    expect(parsed.searchParams.get('limit')).toBe('5000');
+    expect(init.method).toBe('GET');
+    expect(init.credentials).toBe('include');
+  });
+
+  it('defaults to csv and omits optional params when not provided', async () => {
+    const fetchImpl = vi.fn(async () => csvResponse());
+    const ds = makeDS(fetchImpl);
+
+    await ds.exportDownload('task', {});
+
+    const [url] = fetchImpl.mock.calls[0];
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get('format')).toBe('csv');
+    expect(parsed.searchParams.get('fields')).toBeNull();
+    expect(parsed.searchParams.get('orderby')).toBeNull();
+    expect(parsed.searchParams.get('header')).toBeNull();
+    expect(parsed.searchParams.get('limit')).toBeNull();
+  });
+
+  it('serializes the filter to a JSON AST query param', async () => {
+    const fetchImpl = vi.fn(async () => csvResponse());
+    const ds = makeDS(fetchImpl);
+
+    await ds.exportDownload('task', { filter: [['status', '=', 'open']] });
+
+    const [url] = fetchImpl.mock.calls[0];
+    const raw = new URL(url).searchParams.get('filter');
+    expect(raw).toBeTruthy();
+    expect(JSON.parse(raw!)).toEqual([['status', '=', 'open']]);
+  });
+
+  it('throws an error carrying the server message and status on failure', async () => {
+    const fetchImpl = vi.fn(async () =>
+      new Response(JSON.stringify({ error: { message: 'Permission denied' } }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    const ds = makeDS(fetchImpl);
+
+    await expect(ds.exportDownload('task', { format: 'csv' })).rejects.toMatchObject({
+      message: 'Permission denied',
+      status: 403,
+    });
+  });
+});

package/src/getObjectSchema.test.ts

@@ -74,4 +74,40 @@ describe('ObjectStackAdapter.getObjectSchema', () => {
     expect(schema.name).toBe('account');
     expect(Object.keys(schema.fields)).toEqual(['x']);
   });
+
+  it('preserves `validations` (incl. state_machine transitions) — the seam the inline editor depends on', async () => {
+    // Inert-metadata regression guard. The inline select editor filters its
+    // options by the object's `state_machine` validation (objectui#2110). That
+    // feature only works because `getObjectSchema` passes the served
+    // `validations` through untouched — the server enforces the same rule. If a
+    // future change here started stripping or reshaping top-level metadata, the
+    // filter would silently no-op (valid-but-inert) with no error. Pin the
+    // pass-through so the data path can't go dark unnoticed.
+    const { fetchImpl } = makeFetch({
+      name: 'showcase_task',
+      fields: { status: { type: 'select', options: [{ value: 'done', label: 'Done' }] } },
+      validations: [
+        {
+          type: 'state_machine',
+          field: 'status',
+          transitions: { in_review: ['done', 'in_progress'], done: ['in_progress'] },
+        },
+      ],
+    });
+    const adapter = new ObjectStackAdapter({
+      baseUrl: 'http://localhost:3000',
+      autoReconnect: false,
+      fetch: fetchImpl as any,
+    });
+
+    const schema: any = await adapter.getObjectSchema('showcase_task');
+
+    const sm = (schema.validations ?? []).find((v: any) => v?.type === 'state_machine');
+    expect(sm).toBeTruthy();
+    expect(sm.field).toBe('status');
+    // The exact map the consumer filters on — `done` only transitions to
+    // `in_progress` (so the editor must not offer `in_review`).
+    expect(sm.transitions.done).toEqual(['in_progress']);
+    expect(sm.transitions.in_review).toEqual(['done', 'in_progress']);
+  });
 });

package/src/importJob.test.ts

@@ -0,0 +1,71 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+
+/**
+ * Adapter over a mock client `data` namespace. The async import-job methods are
+ * thin pass-throughs to the client SDK, so we assert delegation + argument
+ * shaping, plus graceful degradation when the client lacks the job API.
+ */
+function makeDS(stub: Record<string, any>) {
+  const ds: any = new ObjectStackAdapter({
+    baseUrl: 'http://test.local',
+    fetch: vi.fn(async () => new Response(JSON.stringify({ success: true, data: { capabilities: {}, routes: {} } }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    })),
+  });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  ds.client = { data: stub };
+  return ds;
+}
+
+describe('ObjectStackAdapter async import jobs', () => {
+  it('createImportJob delegates to client.data.createImportJob', async () => {
+    const createImportJob = vi.fn().mockResolvedValue({ jobId: 'imp_1', object: 'task', status: 'pending', total: 2 });
+    const ds = makeDS({ createImportJob });
+    const req = { format: 'json' as const, rows: [{ a: 1 }, { a: 2 }], writeMode: 'upsert' as const, matchFields: ['a'] };
+    const res = await ds.createImportJob('task', req);
+    expect(createImportJob).toHaveBeenCalledTimes(1);
+    expect(createImportJob.mock.calls[0]).toEqual(['task', req]);
+    expect(res).toMatchObject({ jobId: 'imp_1', status: 'pending', total: 2 });
+  });
+
+  it('getImportJobProgress / getImportJobResults / cancelImportJob delegate by jobId', async () => {
+    const getImportJobProgress = vi.fn().mockResolvedValue({ jobId: 'imp_1', status: 'running', percentComplete: 50 });
+    const getImportJobResults = vi.fn().mockResolvedValue({ jobId: 'imp_1', status: 'succeeded', results: [], resultsTruncated: false });
+    const cancelImportJob = vi.fn().mockResolvedValue({ success: true });
+    const ds = makeDS({ createImportJob: vi.fn(), getImportJobProgress, getImportJobResults, cancelImportJob });
+
+    expect((await ds.getImportJobProgress('imp_1')).percentComplete).toBe(50);
+    expect(getImportJobProgress).toHaveBeenCalledWith('imp_1');
+
+    expect((await ds.getImportJobResults('imp_1')).resultsTruncated).toBe(false);
+    expect(getImportJobResults).toHaveBeenCalledWith('imp_1');
+
+    await ds.cancelImportJob('imp_1');
+    expect(cancelImportJob).toHaveBeenCalledWith('imp_1');
+  });
+
+  it('listImportJobs forwards filters and returns the jobs array', async () => {
+    const listImportJobs = vi.fn().mockResolvedValue([{ jobId: 'imp_1', object: 'task', status: 'succeeded' }]);
+    const ds = makeDS({ createImportJob: vi.fn(), listImportJobs });
+    const jobs = await ds.listImportJobs({ object: 'task', status: 'succeeded', limit: 10 });
+    expect(listImportJobs).toHaveBeenCalledWith({ object: 'task', status: 'succeeded', limit: 10 });
+    expect(jobs).toHaveLength(1);
+  });
+
+  it('throws UNSUPPORTED_OPERATION when the client lacks the job API', async () => {
+    const ds = makeDS({ import: vi.fn() }); // sync import only, no createImportJob
+    await expect(ds.createImportJob('task', { format: 'json', rows: [] })).rejects.toMatchObject({ code: 'UNSUPPORTED_OPERATION' });
+    await expect(ds.getImportJobProgress('imp_1')).rejects.toMatchObject({ code: 'UNSUPPORTED_OPERATION' });
+  });
+});

package/src/index.ts

@@ -7,7 +7,22 @@
  */
 
 import { ObjectStackClient, type QueryOptions as ObjectStackQueryOptions } from '@objectstack/client';
-import type { DataSource, QueryParams, QueryResult, FileUploadResult } from '@object-ui/types';
+import type {
+  DataSource,
+  MutationEvent,
+  QueryParams,
+  QueryResult,
+  FileUploadResult,
+  ExportDownloadRequest,
+  ImportRequestOptions,
+  ImportRecordsResult,
+  CreateImportJobResult,
+  ImportJobProgressInfo,
+  ImportJobResultsInfo,
+  ImportJobSummaryInfo,
+  ImportJobUndoResult,
+  ListImportJobsOptions,
+} from '@object-ui/types';
 import { convertFiltersToAST } from '@object-ui/core';
 import { MetadataCache } from './cache/MetadataCache';
 import {
@@ -389,6 +404,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   // so optional collections like sys_presence don't hammer the server with
   // failing requests on every record open / panel render.
   private missingResources = new Set<string>();
+  // 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.
+  private mutationListeners = new Set<(event: MutationEvent<T>) => void>();
 
   constructor(config: {
     baseUrl: string;
@@ -692,9 +712,37 @@ export 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(event: MutationEvent<T>): void {
+    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: (event: MutationEvent<T>) => void): () => void {
+    this.mutationListeners.add(callback);
+    return () => {
+      this.mutationListeners.delete(callback);
+    };
+  }
+
   async create(resource: string, data: Partial<T>): Promise<T> {
     await this.connect();
     const result = await this.client.data.create<T>(resource, data);
+    this.emitMutation({ type: 'create', resource, record: { ...result.record } });
     return result.record;
   }
 
@@ -723,6 +771,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         data,
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
       );
+      this.emitMutation({ type: 'update', resource, id, record: { ...result.record } });
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -748,6 +797,9 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         String(id),
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
       );
+      if (result.deleted) {
+        this.emitMutation({ type: 'delete', resource, id });
+      }
       return result.deleted;
     } catch (err) {
       throw normaliseClientError(err);
@@ -778,6 +830,13 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     if (!ids || ids.length === 0) return 0;
     const records = ids.map((id) => ({ id: String(id), data: patch as any }));
 
+    // Notify subscribers once for the whole batch (not per-id) so a single
+    // "mark all read"/"archive selected" refreshes bound views exactly once.
+    const emitBulk = (count: number): number => {
+      if (count > 0) this.emitMutation({ type: 'update', resource });
+      return count;
+    };
+
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const updateMany = (this.client.data as any).updateMany;
     if (typeof updateMany === 'function') {
@@ -786,10 +845,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // The server returns BatchUpdateResponse { succeeded, failed, ... };
         // fall back to ids.length on adapters that return a bare array.
         if (res && typeof res === 'object' && typeof (res as any).succeeded === 'number') {
-          return (res as any).succeeded as number;
+          return emitBulk((res as any).succeeded as number);
         }
-        if (Array.isArray(res)) return (res as any[]).length;
-        return ids.length;
+        if (Array.isArray(res)) return emitBulk((res as any[]).length);
+        return emitBulk(ids.length);
       } catch (err) {
         throw normaliseClientError(err);
       }
@@ -805,7 +864,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // continueOnError semantics — swallow per-row errors
       }
     }
-    return succeeded;
+    return emitBulk(succeeded);
   }
 
   /**
@@ -823,17 +882,23 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     if (!ids || ids.length === 0) return 0;
     const strIds = ids.map((id) => String(id));
 
+    // Notify subscribers once for the whole batch (see bulkUpdate).
+    const emitBulk = (count: number): number => {
+      if (count > 0) this.emitMutation({ type: 'delete', resource });
+      return count;
+    };
+
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const deleteMany = (this.client.data as any).deleteMany;
     if (typeof deleteMany === 'function') {
       try {
         const res = await deleteMany(resource, strIds, { continueOnError: true });
         if (res && typeof res === 'object' && typeof (res as any).succeeded === 'number') {
-          return (res as any).succeeded as number;
+          return emitBulk((res as any).succeeded as number);
         }
-        if (Array.isArray(res)) return (res as any[]).length;
+        if (Array.isArray(res)) return emitBulk((res as any[]).length);
         // deleteMany historically returns void on success — assume all hit.
-        return strIds.length;
+        return emitBulk(strIds.length);
       } catch (err) {
         throw normaliseClientError(err);
       }
@@ -849,7 +914,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // continueOnError semantics — swallow per-row errors
       }
     }
-    return succeeded;
+    return emitBulk(succeeded);
   }
 
   /**
@@ -1047,6 +1112,183 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<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.
+   */
+  async importRecords(
+    resource: string,
+    request: ImportRequestOptions,
+  ): Promise<ImportRecordsResult> {
+    await this.connect();
+    const importFn = (this.client.data as { import?: unknown }).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 as (
+        object: string,
+        req: ImportRequestOptions,
+      ) => Promise<ImportRecordsResult>).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}.
+   */
+  private importJobApi(): {
+    createImportJob: (object: string, req: ImportRequestOptions) => Promise<CreateImportJobResult>;
+    getImportJobProgress: (jobId: string) => Promise<ImportJobProgressInfo>;
+    getImportJobResults: (jobId: string) => Promise<ImportJobResultsInfo>;
+    listImportJobs: (query: ListImportJobsOptions) => Promise<ImportJobSummaryInfo[]>;
+    cancelImportJob: (jobId: string) => Promise<{ success: boolean }>;
+    undoImportJob: (jobId: string) => Promise<ImportJobUndoResult>;
+  } | undefined {
+    const d = this.client.data as Record<string, unknown>;
+    if (typeof d.createImportJob !== 'function') return undefined;
+    return d as any;
+  }
+
+  /**
+   * 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: string,
+    request: ImportRequestOptions,
+  ): Promise<CreateImportJobResult> {
+    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: string): Promise<ImportJobProgressInfo> {
+    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: string): Promise<ImportJobResultsInfo> {
+    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: ListImportJobsOptions = {}): Promise<ImportJobSummaryInfo[]> {
+    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: string): Promise<void> {
+    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: string): Promise<ImportJobUndoResult> {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api || typeof (api as { undoImportJob?: unknown }).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.
    */
@@ -1182,6 +1424,66 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     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: string, request: ExportDownloadRequest = {}): Promise<Blob> {
+    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');
+    }
+    // Sort → server `orderby` shorthand: "field:dir,field2:dir".
+    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);
+    }
+    // Filter → AST tuples, same translation the list GET path uses.
+    if (request.filter !== undefined && request.filter !== null) {
+      const translated = translateFilterToAST(request.filter);
+      if (translated !== undefined) {
+        queryParams.set('filter', JSON.stringify(translated));
+      }
+    }
+
+    const baseUrl = this.baseUrl.replace(/\/$/, '');
+    // Avoid doubling /api/v1 if baseUrl already includes the version suffix.
+    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: Record<string, string> = { ...this.getAuthHeaders() };
+    // `credentials: 'include'` carries the session cookie for the browser
+    // console (which authenticates by cookie, not a bearer token).
+    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) as any;
+      err.status = res.status;
+      throw err;
+    }
+    return await res.blob();
+  }
+
   /**
    * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
    * Maps OData-style conventions to ObjectStack conventions.
@@ -2334,6 +2636,7 @@ export type {
   MetadataDeleteOptions,
   MetadataHistoryOptions,
   MetadataError,
+  MetadataValidationIssue,
   MetadataLayered,
   MetadataReference,
   MetadataDiagnostics,

package/src/metadata-client.test.ts

@@ -122,6 +122,36 @@ describe('MetadataClient', () => {
     });
   });
 
+  it('extracts message, code + field-anchored issues from the dispatcher error shape', async () => {
+    // The dispatcher sends `error` as an OBJECT { message, code, details:{ code, issues } }.
+    // Reading `.message` (not String(object) → "[object Object]") and surfacing
+    // `details.issues` is what lets the Studio point at the offending field.
+    const c = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      fetch: mockFetch(async () =>
+        new Response(
+          JSON.stringify({
+            success: false,
+            error: {
+              message: '[invalid_metadata] object/bad failed spec validation: label: Required',
+              code: 422,
+              details: {
+                code: 'invalid_metadata',
+                issues: [{ path: 'label', message: 'Required', code: 'invalid_type' }],
+              },
+            },
+          }),
+          { status: 422, headers: { 'content-type': 'application/json' } },
+        )),
+    });
+    await expect(c.save('object', 'bad', {})).rejects.toMatchObject({
+      status: 422,
+      code: 'invalid_metadata',
+      message: '[invalid_metadata] object/bad failed spec validation: label: Required',
+      issues: [{ path: 'label', message: 'Required', code: 'invalid_type' }],
+    });
+  });
+
   it('listDrafts requests /meta/_drafts with packageId + type and parses {drafts}', async () => {
     const seen: string[] = [];
     const c = new MetadataClient({