@object-ui/data-objectstack 6.2.3 → 7.1.0

package/src/index.ts

@@ -603,7 +603,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       // which parses `populate` (comma-separated) into an array for lookup expansion.
       // We use a raw request because the client SDK's data.find() QueryOptions
       // interface does not include populate/expand fields.
-      if (params?.$expand && params.$expand.length > 0) {
+      if ((params?.$expand && params.$expand.length > 0)
+          || (params?.$search != null && String(params.$search).trim() !== '')) {
+        // The client SDK's data.find() QueryOptions drops `$search`; route through
+        // the raw GET so the term reaches protocol.findData → the metadata-driven
+        // search executor (ADR-0061).
         const result = await this.rawFindWithPopulate(resource, params);
         return this.normalizeQueryResult(result, params);
       }
@@ -857,6 +861,37 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * @param data - Array of records to process
    * @returns Promise resolving to array of results
    */
+  /**
+   * Cross-object transactional batch (ObjectStack #1604). Runs the operations
+   * in ONE server transaction — commit all or roll back all. A field value of
+   * `{ $ref: <earlier op index> }` resolves to that op's created id, so a child
+   * can reference its parent created earlier in the same batch (master-detail).
+   */
+  async batchTransaction(
+    operations: Array<{ object: string; action?: 'create' | 'update' | 'delete'; data?: any; id?: string }>,
+  ): Promise<{ results: any[] }> {
+    const url = `${this.baseUrl}/api/v1/batch`;
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
+      // Send the session cookie too: in the browser console auth is cookie-based
+      // (no bearer `token`), so without `credentials: 'include'` this raw fetch
+      // is unauthenticated — every master-detail batch save would 401. Bearer
+      // (server-to-server) and cookie (console) auth now both work.
+      credentials: 'include',
+      body: JSON.stringify({ operations }),
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: response.statusText }));
+      throw new ObjectStackError(
+        error.error || error.message || `Batch failed with status ${response.status}`,
+        'BATCH_ERROR',
+        response.status,
+      );
+    }
+    return response.json();
+  }
+
   async bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]> {
     await this.connect();
 
@@ -1027,16 +1062,22 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       };
     }
 
-    const resultObj = result as { records?: T[]; total?: number; value?: T[]; count?: number };
+    const resultObj = result as { records?: T[]; total?: number; value?: T[]; count?: number; hasMore?: boolean };
     const records = resultObj.records || resultObj.value || [];
     const total = resultObj.total ?? resultObj.count ?? records.length;
+    // Prefer the server's `hasMore` (real server-side pagination, framework
+    // issue #2212). Fall back to the page-local estimate (a full page implies
+    // there may be more) only when the server doesn't report it.
+    const hasMore = typeof resultObj.hasMore === 'boolean'
+      ? resultObj.hasMore
+      : (params?.$top ? records.length === params.$top : false);
     return {
       data: records,
       total,
       // Calculate page number safely
       page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
       pageSize: params?.$top,
-      hasMore: params?.$top ? records.length === params.$top : false,
+      hasMore,
     };
   }
 
@@ -1062,6 +1103,15 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       queryParams.set('skip', String(params.$skip));
     }
 
+    // Full-text search (ADR-0061). The server resolves which fields to match
+    // from object metadata; the client only sends the term (+ optional override).
+    if (params.$search != null && String(params.$search).trim() !== '') {
+      queryParams.set('search', String(params.$search).trim());
+    }
+    if (params.$searchFields && params.$searchFields.length > 0) {
+      queryParams.set('searchFields', params.$searchFields.join(','));
+    }
+
     // Selection — always include `id` to ensure records can be identified
     // for navigation/selection even when callers omit it from $select.
     if (params.$select && params.$select.length > 0) {
@@ -1219,6 +1269,13 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       options.top = params.$top;
     }
 
+    if (params.$search != null && String(params.$search).trim() !== '') {
+      (options as Record<string, unknown>).search = String(params.$search).trim();
+    }
+    if (params.$searchFields && params.$searchFields.length > 0) {
+      (options as Record<string, unknown>).searchFields = params.$searchFields;
+    }
+
     return options;
   }
 
@@ -1233,17 +1290,22 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     await this.connect();
     
     try {
-      // Use cache with automatic fetching
-      const schema = await this.metadataCache.get(objectName, async () => {
-        const result: any = await this.client.meta.getItem('object', objectName);
-        
-        // Unwrap 'item' property if present (common API response wrapper)
-        if (result && result.item) {
-          return result.item;
-        }
-
-        return result;
-      });
+      // Use cache with automatic fetching. The cache is keyed by object name
+      // only (locale-independent); a language switch wipes it wholesale via
+      // `clearCache()` so the next read re-fetches in the new locale — see the
+      // shell's locale remount (issue #1319). Keeping the key locale-free here
+      // means a metadata *write* still invalidates the single entry it knows
+      // about, without having to fan out across every cached locale.
+      // Read through a cache-revalidating fetch (see fetchObjectSchemaFresh):
+      // the server marks single-object metadata `public, max-age=3600`, so a
+      // plain fetch would keep serving the pre-publish schema from the browser
+      // HTTP cache for up to an hour — and the create/edit form (which reads
+      // getObjectSchema) would never show a field added + published in this
+      // session. The list endpoint is uncached, which is why list views already
+      // refresh on publish.
+      const schema = await this.metadataCache.get(objectName, () =>
+        this.fetchObjectSchemaFresh(objectName),
+      );
       
       return schema;
     } catch (error: unknown) {
@@ -1262,6 +1324,59 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Fetch a single object's schema while always revalidating the browser cache.
+   *
+   * The server serves `GET /api/v1/meta/object/:name` with
+   * `Cache-Control: public, max-age=3600`, so the default `fetch` the SDK uses
+   * keeps returning the same response from the browser HTTP cache for up to an
+   * hour without contacting the origin. Because the create/edit form reads the
+   * object schema through {@link getObjectSchema}, a field added + published in
+   * the same session never appears in the form even though it is live (the LIST
+   * endpoint, `/meta/object`, is uncached — which is why list views update).
+   *
+   * Issuing the read with `cache: 'no-cache'` forces a conditional revalidation
+   * (`If-None-Match`): a changed ETag returns the fresh schema, an unchanged one
+   * still gets a cheap `304`. We go through `fetchImpl` (the adapter's
+   * authenticated fetch) rather than `client.meta.getItem` because the SDK does
+   * not expose the request cache mode.
+   */
+  private async fetchObjectSchemaFresh(objectName: string): Promise<unknown> {
+    const baseUrl = (this.baseUrl || '').replace(/\/$/, '');
+    // Avoid doubling /api/v1 when baseUrl already carries the version suffix
+    // (mirrors rawFindWithPopulate).
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const metaPath = hasApiVersionSuffix ? '/meta' : '/api/v1/meta';
+    const url = `${baseUrl}${metaPath}/object/${encodeURIComponent(objectName)}`;
+
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    // Bearer (server-to-server) callers configure `this.token`; cookie/console
+    // auth is injected by `fetchImpl` (the authenticated fetch wrapper).
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+
+    const res = await this.fetchImpl(url, {
+      method: 'GET',
+      headers,
+      // Revalidate instead of serving the stale `max-age` body (see doc above).
+      cache: 'no-cache',
+    });
+
+    if (!res.ok) {
+      const errBody: any = await res.json().catch(() => ({ message: res.statusText }));
+      const err: any = new Error(errBody?.error?.message || errBody?.message || res.statusText);
+      err.status = res.status;
+      throw err;
+    }
+
+    const body: any = await res.json();
+    // Unwrap defensively across server/SDK response shapes: the standard
+    // `{ success, data }` envelope, an `{ item }` wrapper, or the bare item.
+    const data = body && typeof body === 'object' && 'success' in body && 'data' in body ? body.data : body;
+    return data && typeof data === 'object' && 'item' in data ? data.item : data;
+  }
+
   /**
    * Get access to the underlying ObjectStack client for advanced operations.
    */
@@ -1348,8 +1463,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     try {
       const cacheKey = `view:${objectName}:${viewId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        // Try meta.getItem for view metadata
-        const result: any = await this.client.meta.getItem(objectName, viewId);
+        // Views are an independent metadata type (ADR-0017) — the first
+        // getItem argument is the metadata TYPE, not the object name.
+        // (Passing objectName here hit /meta/<object>/<view> and always 404ed.)
+        const result: any = await this.client.meta.getItem('view', viewId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -1427,13 +1544,43 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       const items: any[] = Array.isArray(result?.items)
         ? result.items
         : Array.isArray(result) ? result : [];
+      // This feeds the list-view switcher (ViewTabBar), so it must return
+      // LIST-family views only. The backend now exposes each view as an
+      // independent ViewItem carrying a `viewKind` discriminant (ADR-0017);
+      // form-family views (`form`/`detail`) are record forms, not list tabs,
+      // and must be excluded — otherwise e.g. `crm_activity.default` (a form)
+      // leaks in as a spurious switcher tab. Bare specs without `viewKind`
+      // (legacy artifacts / saved views) are kept as list views.
+      const FORM_FAMILY = new Set(['form', 'detail']);
       return items.filter((v: any) => {
         if (!v) return false;
         // Handle both bare view spec and `{list: {...}}` artifact wrapper
         const spec = v.list ?? v;
         const obj = spec?.data?.object ?? spec?.object ?? spec?.objectName;
-        return obj === objectName;
-      }).map((v: any) => v.list ?? v);
+        if (obj !== objectName) return false;
+        const viewKind = v.viewKind ?? spec?.viewKind;
+        return !(viewKind && FORM_FAMILY.has(viewKind));
+      }).map((v: any) => {
+        const spec = v.list ?? v;
+        // Canonical ViewItem (ADR-0017) carries its body under `config`;
+        // the display `type` (grid/kanban/gallery/…) lives at `config.type`,
+        // and only the list/form *family* sits at the top level (`viewKind`).
+        // Flatten `config` up to the legacy NamedListView shape the switcher +
+        // ObjectView consume — mirroring MetadataProvider.mergeViewsIntoObjects
+        // so the two paths don't drift. Without this an un-flattened item has
+        // no top-level `type`, so ObjectView's saved-view normalization defaults
+        // it to 'grid' and overrides the metadata entry — a kanban/gallery/
+        // calendar view then silently renders as a plain table.
+        if (spec && spec.config && typeof spec.config === 'object') {
+          return {
+            ...spec.config,
+            name: spec.name ?? spec.config.name,
+            label: spec.label ?? spec.config.label,
+            isDefault: !!spec.isDefault,
+          };
+        }
+        return spec;
+      });
     } catch (err) {
       console.warn('[OBJECTSTACKDataSource] listViews failed:', err);
       return [];
@@ -1732,6 +1879,111 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Run a semantic-layer `dataset` (ADR-0021) and return chart-ready rows.
+   *
+   * Posts to `POST /api/v1/analytics/dataset/query` (see `@objectstack/rest`
+   * `registerAnalyticsEndpoints`). Accepts either a saved dataset name or an
+   * inline draft definition — the inline form is what the Studio dataset
+   * editor sends to preview an unsaved draft. The adapter's bearer token is
+   * forwarded so tenant/RLS scoping (ADR-0021 D-C) is enforced server-side.
+   *
+   * Unlike {@link aggregate}, this does NOT fall back to client-side
+   * aggregation: cross-object joins can only run on the server, so a failure
+   * is surfaced to the caller (the preview panel shows the error) rather than
+   * silently returning wrong numbers.
+   *
+   * @param dataset - An inline dataset definition (draft) OR a saved dataset name.
+   * @param selection - Dimension/measure names to project + runtime directives.
+   */
+  async queryDataset(
+    dataset: Record<string, unknown> | string,
+    selection: {
+      dimensions?: string[];
+      measures: string[];
+      runtimeFilter?: Record<string, unknown>;
+      timeDimensions?: unknown[];
+      compareTo?: { kind: 'previousPeriod' | 'previousYear'; dimension: string };
+      order?: Record<string, 'asc' | 'desc'>;
+      limit?: number;
+      offset?: number;
+      timezone?: string;
+      /** Marginal-aggregate groupings (e.g. `[rows, [colDim], []]`) — server
+       *  computes each subtotal with the measure's TRUE aggregate (never client
+       *  re-derived). `[]` is the grand total. */
+      totals?: { groupings: string[][] };
+    },
+  ): Promise<{
+    rows: Array<Record<string, unknown>>;
+    /** Column metadata: a display `label` (dimensions and measures), and a
+     *  measure's numeral `format` + declared `currency` for value formatting. */
+    fields: Array<{ name: string; type: string; label?: string; format?: string; currency?: string }>;
+    /** ADR-0021 D2 drill-through: the dataset's base object (records to drill into). */
+    object?: string;
+    /** Drillable dimension NAME → underlying object FIELD name. */
+    dimensionFields?: Record<string, string>;
+    /** Raw grouped values per row (aligned to `rows` by index) for drill filters. */
+    drillRawRows?: Array<Record<string, unknown>>;
+    /** Server-computed marginal aggregates, one entry per requested grouping. */
+    totals?: Array<{ dimensions: string[]; rows: Array<Record<string, unknown>> }>;
+  }> {
+    await this.connect();
+    const base = (this.baseUrl || '').replace(/\/$/, '');
+    const url = `${base}/api/v1/analytics/dataset/query`;
+    // ADR-0037 P3 — draft data preview. Preview mode is URL-keyed by design
+    // (`?preview=draft` flips the whole document, incl. the Live Canvas
+    // iframe), so the adapter reads it straight off the location rather than
+    // threading a React context down through every widget package. When set,
+    // the server overlays the pending seed draft's rows on the dataset query
+    // and resolves draft-overlaid dataset definitions.
+    const previewDrafts =
+      typeof window !== 'undefined' &&
+      new URLSearchParams(window.location.search).get('preview') === 'draft';
+    const requestBody = typeof dataset === 'string'
+      ? { datasetName: dataset, selection, ...(previewDrafts ? { previewDrafts: true } : {}) }
+      : { dataset, selection, ...(previewDrafts ? { previewDrafts: true } : {}) };
+
+    const res = await this.fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}),
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    if (!res.ok) {
+      let detail = '';
+      try {
+        const errBody = await res.json();
+        detail = errBody?.message || errBody?.error || JSON.stringify(errBody);
+      } catch { /* non-JSON error body */ }
+      throw new Error(`Dataset query failed: ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ''}`);
+    }
+
+    const payload = await res.json();
+    // Unwrap the standard `{ success, data }` envelope when present.
+    const data = payload && typeof payload === 'object' && 'success' in payload && 'data' in payload
+      ? (payload as { data: unknown }).data
+      : payload;
+    const rows = Array.isArray((data as any)?.rows)
+      ? (data as any).rows
+      : (Array.isArray(data) ? (data as any) : []);
+    const fields = Array.isArray((data as any)?.fields) ? (data as any).fields : [];
+    // Drill-through metadata (ADR-0021 D2): the server exposes the dataset's
+    // base object + drillable dimension→field mapping, plus a parallel array of
+    // RAW grouped values (the rows themselves carry display labels), so a host
+    // can build an exact-match filter from a clicked bucket.
+    const object = typeof (data as any)?.object === 'string' ? (data as any).object : undefined;
+    const dimensionFields =
+      (data as any)?.dimensionFields && typeof (data as any).dimensionFields === 'object'
+        ? ((data as any).dimensionFields as Record<string, string>)
+        : undefined;
+    const drillRawRows = Array.isArray((data as any)?.drillRawRows) ? (data as any).drillRawRows : undefined;
+    const totals = Array.isArray((data as any)?.totals) ? (data as any).totals : undefined;
+    return { rows, fields, object, dimensionFields, drillRawRows, totals };
+  }
+
   /** Client-side aggregation fallback */
   private aggregateClientSide(records: any[], params: { field: string; function: string; groupBy: string }): any[] {
     const { field, function: aggFn, groupBy } = params;
@@ -2076,11 +2328,20 @@ export { MetadataClient } from './metadata-client';
 export type {
   MetadataClientConfig,
   MetadataListOptions,
+  MetadataDraftHeader,
   MetadataSaveOptions,
+  MetadataGetOptions,
+  MetadataDeleteOptions,
   MetadataHistoryOptions,
   MetadataError,
   MetadataLayered,
   MetadataReference,
+  MetadataDiagnostics,
+  MetadataDiagnosticsOptions,
+  MetadataDiagnosticsEntry,
+  MetadataDiagnosticsSummary,
+  MetadataAuditEntry,
+  MetadataAuditResponse,
 } from './metadata-client';
 
 export { SecurityManager } from './security';

package/src/listViews.test.ts

@@ -0,0 +1,78 @@
+/**
+ * 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';
+
+/**
+ * `listViews(object)` feeds the list-view switcher (ObjectView → ViewTabBar),
+ * so it must return LIST-family views only. The backend exposes each view as
+ * an independent ViewItem carrying a `viewKind` discriminant (ADR-0017); a
+ * form-family view (e.g. `crm_activity.default`) must NOT leak in as a tab.
+ */
+function makeDS(items: 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 = { meta: { getItems: vi.fn(async () => ({ items })) } };
+  return ds;
+}
+
+describe('ObjectStackDataSource.listViews', () => {
+  // The crm_activity view set as the framework expands it.
+  const listAll = {
+    name: 'crm_activity.all', object: 'crm_activity', viewKind: 'list', isDefault: true,
+    label: 'All Activities', config: { type: 'grid', data: { object: 'crm_activity' } },
+  };
+  const listCalendar = {
+    name: 'crm_activity.calendar', object: 'crm_activity', viewKind: 'list',
+    label: 'Activity Calendar', config: { type: 'calendar', data: { object: 'crm_activity' } },
+  };
+  const formDefault = {
+    name: 'crm_activity.default', object: 'crm_activity', viewKind: 'form',
+    label: 'Activity', config: { type: 'simple' },
+  };
+
+  it('excludes form-family ViewItems from the list-view switcher', async () => {
+    const ds = makeDS([listAll, listCalendar, formDefault]);
+    const views = await ds.listViews('crm_activity');
+    const names = views.map((v: any) => v.name).sort();
+    expect(names).toEqual(['crm_activity.all', 'crm_activity.calendar']);
+    // The form view is the original leak — it must be gone.
+    expect(views.find((v: any) => v.name === 'crm_activity.default')).toBeUndefined();
+  });
+
+  it('excludes detail-family views too', async () => {
+    const detail = { name: 'crm_activity.detail', object: 'crm_activity', viewKind: 'detail', config: {} };
+    const ds = makeDS([listAll, detail]);
+    const views = await ds.listViews('crm_activity');
+    expect(views.map((v: any) => v.name)).toEqual(['crm_activity.all']);
+  });
+
+  it('filters by object binding', async () => {
+    const otherList = { name: 'crm_lead.all', object: 'crm_lead', viewKind: 'list', config: {} };
+    const ds = makeDS([listAll, otherList]);
+    const views = await ds.listViews('crm_activity');
+    expect(views.map((v: any) => v.name)).toEqual(['crm_activity.all']);
+  });
+
+  it('keeps legacy bare specs without a viewKind (saved/list views)', async () => {
+    const legacy = { name: 'saved_grid', object: 'crm_activity', type: 'grid' };
+    const wrapped = { list: { name: 'wrapped_grid', object: 'crm_activity', type: 'grid' } };
+    const ds = makeDS([legacy, wrapped]);
+    const views = await ds.listViews('crm_activity');
+    expect(views.map((v: any) => v.name).sort()).toEqual(['saved_grid', 'wrapped_grid']);
+  });
+});

package/src/metadata-client.test.ts

@@ -121,4 +121,145 @@ describe('MetadataClient', () => {
       message: 'metadata_conflict',
     });
   });
+
+  it('listDrafts requests /meta/_drafts with packageId + type and parses {drafts}', async () => {
+    const seen: string[] = [];
+    const c = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      fetch: mockFetch(async (url) => {
+        seen.push(url);
+        return jsonResponse({
+          drafts: [{ type: 'object', name: 'course', packageId: 'app.edu', updatedAt: 't', updatedBy: 'ai' }],
+        });
+      }),
+    });
+    const out = await c.listDrafts({ packageId: 'app.edu', type: 'object' });
+    expect(seen[0]).toBe('http://localhost:3000/api/v1/meta/_drafts?packageId=app.edu&type=object');
+    expect(out).toEqual([
+      { type: 'object', name: 'course', packageId: 'app.edu', updatedAt: 't', updatedBy: 'ai' },
+    ]);
+  });
+
+  it('listDrafts tolerates the {data:{drafts}} envelope and a bare array', async () => {
+    const enveloped = new MetadataClient({
+      baseUrl: '',
+      fetch: mockFetch(async () =>
+        jsonResponse({ data: { drafts: [{ type: 'view', name: 'v', packageId: null, updatedAt: null, updatedBy: null }] } })),
+    });
+    expect((await enveloped.listDrafts()).map((d) => d.name)).toEqual(['v']);
+
+    const bare = new MetadataClient({
+      baseUrl: '',
+      fetch: mockFetch(async () =>
+        jsonResponse([{ type: 'object', name: 'b', packageId: null, updatedAt: null, updatedBy: null }])),
+    });
+    expect((await bare.listDrafts()).map((d) => d.name)).toEqual(['b']);
+  });
+
+  it('publishDraft POSTs /meta/:type/:name/publish (promotes a draft by ref, no package needed)', async () => {
+    const seen: { url: string; method?: string }[] = [];
+    const c = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      fetch: mockFetch(async (url, init) => {
+        seen.push({ url, method: init?.method });
+        return jsonResponse({ success: true });
+      }),
+    });
+    await c.publishDraft('dashboard', 'sales_dashboard');
+    expect(seen[0]?.method).toBe('POST');
+    expect(seen[0]?.url).toBe('http://localhost:3000/api/v1/meta/dashboard/sales_dashboard/publish');
+  });
+
+  it('publishDraft throws on a non-ok response', async () => {
+    const c = new MetadataClient({
+      baseUrl: '',
+      fetch: mockFetch(async () => new Response('nope', { status: 500 })),
+    });
+    await expect(c.publishDraft('view', 'x')).rejects.toBeTruthy();
+  });
+
+  it('publishDraft returns the result (incl. seedApplied) and unwraps the {data} envelope', async () => {
+    // Flat shape (rest-server passes protocol result through).
+    const flat = new MetadataClient({
+      baseUrl: '',
+      fetch: mockFetch(async () =>
+        jsonResponse({ success: true, seedApplied: { success: false, error: 'no readable seed bodies' } })),
+    });
+    const r1 = await flat.publishDraft('seed', 'job_sample');
+    expect(r1.seedApplied).toEqual({ success: false, error: 'no readable seed bodies' });
+
+    // Dispatcher `{ success, data: {...} }` envelope.
+    const enveloped = new MetadataClient({
+      baseUrl: '',
+      fetch: mockFetch(async () =>
+        jsonResponse({ success: true, data: { success: true, seedApplied: { success: true, inserted: 6, updated: 0 } } })),
+    });
+    const r2 = await enveloped.publishDraft('seed', 'candidate_sample');
+    expect(r2.seedApplied).toEqual({ success: true, inserted: 6, updated: 0 });
+  });
+});
+
+describe('MetadataClient — ADR-0037 previewDrafts', () => {
+  function previewClient(opts: { previewDrafts?: boolean; environmentId?: string } = {}) {
+    const urls: string[] = [];
+    const c = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      ...opts,
+      fetch: mockFetch(async (url) => {
+        urls.push(url);
+        return jsonResponse([{ name: 'account' }]);
+      }),
+    });
+    return { c, urls };
+  }
+
+  it('list() and get() append ?preview=draft when enabled', async () => {
+    const { c, urls } = previewClient({ previewDrafts: true });
+    await c.list('object');
+    await c.get('object', 'account');
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object?preview=draft');
+    expect(urls[1]).toBe('http://localhost:3000/api/v1/meta/object/account?preview=draft');
+  });
+
+  it('combines preview with the package filter on list()', async () => {
+    const { c, urls } = previewClient({ previewDrafts: true });
+    await c.list('object', { packageId: 'app.crm' });
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object?package=app.crm&preview=draft');
+  });
+
+  it('an explicit state=draft read wins over the overlay flag', async () => {
+    const { c, urls } = previewClient({ previewDrafts: true });
+    await c.get('object', 'account', { state: 'draft' });
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object/account?state=draft');
+  });
+
+  it('default client never sends the flag', async () => {
+    const { c, urls } = previewClient();
+    await c.list('object');
+    await c.get('object', 'account');
+    expect(urls[0]).not.toContain('preview');
+    expect(urls[1]).not.toContain('preview');
+  });
+
+  it('withPreviewDrafts derives a preview client and PRESERVES the environment scope', async () => {
+    const { c } = previewClient({ environmentId: 'env_1' });
+    const p = c.withPreviewDrafts(true);
+    expect(p.previewDrafts).toBe(true);
+    // Same instance back when the flag already matches.
+    expect(p.withPreviewDrafts(true)).toBe(p);
+    // Environment-scoped path survives the derivation (regression guard:
+    // a naive rebuild dropped /environments/:id from the base).
+    const urls: string[] = [];
+    const scoped = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      environmentId: 'env_1',
+      previewDrafts: false,
+      fetch: mockFetch(async (url) => {
+        urls.push(url);
+        return jsonResponse([]);
+      }),
+    }).withPreviewDrafts(true);
+    await scoped.list('object');
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/environments/env_1/meta/object?preview=draft');
+  });
 });