@object-ui/data-objectstack 6.0.4 → 6.2.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @object-ui/data-objectstack
 
+## 6.2.0
+
+### Minor Changes
+
+- ec8dcde: Add visual editing for object & field metadata in the Setup app.
+
+  **`@object-ui/data-objectstack`** — new `MetadataClient` class. A thin,
+  auth-friendly wrapper over the framework's `/api/v1/meta/*` REST
+  endpoints (list / get / save / reset / history), with first-class
+  support for `If-Match` (optimistic concurrency), `X-Actor` (audit
+  attribution), environment-scoped paths
+  (`/environments/:id/meta/*`), and 404-as-null semantics. Use
+  `new MetadataClient({ baseUrl })` or `client.withEnvironment(id)` to
+  target a specific environment.
+
+  **`@object-ui/plugin-designer`** — two new route-ready pages that
+  together close the "Data Model" management loop in the Setup app:
+  - `MetadataObjectsPage` — lists every object schema (via
+    `MetadataClient.list('object')`), renders the existing
+    `ObjectManager`, and persists edits/deletes through PUT/DELETE on
+    the metadata REST surface. Honours `allowRuntimeCreate` and
+    surfaces server errors verbatim.
+  - `MetadataFieldsPage` — for a single object, loads the parent
+    schema, projects `fields` into the existing `FieldDesigner`, and
+    on save merges the edited field map back into the object before
+    issuing a single PUT. Preserves unknown per-field attributes so
+    nothing the designer doesn't render is dropped.
+
+  Both pages take either a pre-built `MetadataClient` or a
+  `MetadataClientConfig`; neither imposes a routing convention on the
+  host app — they can be mounted anywhere (e.g.
+  `/apps/setup/_meta/object` and `/apps/setup/_meta/object/:name/fields`).
+
+  These additions do not modify the underlying `ObjectManager` /
+  `FieldDesigner` components, which remain pure controlled-input
+  components usable in non-REST contexts.
+
+### Patch Changes
+
+- fe3c1d3: Metadata Admin engine — unified UI for all 27 metadata types.
+
+  A generic, schema-driven admin shell that replaces the old per-type
+  bespoke pages with a single registry-driven engine. Admins can now browse,
+  create, override, diff, and roll back every registered metadata type from
+  the Setup app → _All Metadata Types_.
+
+  ### New: `@object-ui/app-shell` views/metadata-admin
+  - **`MetadataDirectoryPage`** — auto-grouped tile directory by domain, with
+    free-text search, domain chips, and a _Writable only_ filter.
+  - **`MetadataResourceListPage` / `MetadataResourceEditPage` / `…CreatePage` / `…HistoryPage`** —
+    generic CRUD shell. Uses the new `/meta/types` schema field to render
+    SchemaForm; uses `?layers=code,overlay,effective` to power a 3-state diff
+    tab; uses `/references` to warn before destructive deletes.
+  - **`MetadataQuickFind`** — Cmd+Shift+M palette searching across types and
+    items.
+  - **`PermissionMatrixEditor`** — Salesforce-style matrix custom editor for
+    `type=permission`. Objects × CRUD/VAMA/lifecycle columns with cascade
+    rules (viewAllRecords ⟹ allowRead, etc.), expandable per-object field
+    R/W subtable, bulk-set (R / CRUD / All / None), filter, _only granted_
+    toggle, destructive-change confirmation, profile switch.
+  - **`DesignerEditorWrapper`** — generic load–edit–save shell that hosts any
+    bespoke designer (`ObjectViewConfigurator`, `DashboardEditor`,
+    `PageCanvasEditor`, …). Handles dirty tracking, Save / Reset / Refresh /
+    History buttons, and the read-only fallback when `allowOrgOverride` is
+    false.
+  - **`i18n.ts`** — bilingual (`en-US`, `zh-CN`) bundle for built-in type
+    labels, domain labels, and engine UI strings, with `detectLocale()` and a
+    `t(key)` helper.
+
+  ### New routing variant
+  - App nav now supports `{ type: 'component', componentRef, params? }` items.
+    `AppContent` resolves them through the existing `ComponentRegistry`.
+  - Built-in components registered: `metadata:directory`, `metadata:resource`,
+    `metadata:object/edit` (FieldsPage), `metadata:permission/edit`
+    (PermissionMatrixEditor), and lazy designer wrappers for view / dashboard
+    / page.
+
+  ### Plugin-designer
+  - Lazy-exported `ObjectManager`, `FieldDesigner`, `ObjectViewConfigurator`,
+    `DashboardEditor`, `PageCanvasEditor`, `MetadataObjectsPage`, and
+    `MetadataFieldsPage` so the engine can mount them on demand.
+
+  The temporary `/dev/meta` route is removed. Setup app navigation flows
+  through the new component routes.
+  - @object-ui/types@6.2.0
+  - @object-ui/core@6.2.0
+
+## 6.1.0
+
+### Patch Changes
+
+- Updated dependencies [991b62d]
+  - @object-ui/core@6.1.0
+  - @object-ui/types@6.1.0
+
 ## 6.0.4
 
 ### Patch Changes

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   ConcurrentUpdateError: () => ConcurrentUpdateError,
   ConnectionError: () => ConnectionError,
   IntegrationManager: () => IntegrationManager,
+  MetadataClient: () => MetadataClient,
   MetadataNotFoundError: () => MetadataNotFoundError,
   ObjectStackAdapter: () => ObjectStackAdapter,
   ObjectStackError: () => ObjectStackError,
@@ -586,15 +587,21 @@ function createObjectStackUserStateAdapter(options) {
   let cachedRowId = null;
   const findExisting = async () => {
     const params = {
-      filter: {
+      $filter: {
         user_id: userId,
         key
       },
-      limit: 1
+      $top: 1
     };
     const result = await dataSource.find(resource, params);
     const rows = result?.data ?? [];
-    return rows.length > 0 ? rows[0] : null;
+    const match = rows.find((r) => {
+      if (!r) return false;
+      const userMismatch = r.user_id !== void 0 && r.user_id !== userId;
+      const keyMismatch = r.key !== void 0 && r.key !== key;
+      return !userMismatch && !keyMismatch;
+    });
+    return match ?? null;
   };
   const decodeValue = (value) => {
     if (Array.isArray(value)) return value;
@@ -773,6 +780,181 @@ var IntegrationManager = class {
   }
 };
 
+// src/metadata-client.ts
+var META_PREFIX = "/meta";
+var API_PREFIX = "/api/v1";
+function buildBase(config) {
+  const trimmed = config.baseUrl.replace(/\/+$/, "");
+  const scoped = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
+  if (/\/api\/v\d+$/i.test(trimmed)) {
+    const stripped = trimmed.replace(/\/api\/v\d+$/i, "");
+    const scopedNoApi = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
+    return `${stripped}${scopedNoApi}`;
+  }
+  return `${trimmed}${scoped}`;
+}
+async function parseError(res) {
+  let body;
+  try {
+    body = await res.json();
+  } 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);
+  err.status = res.status;
+  err.body = body;
+  if (body && typeof body === "object" && "code" in body) {
+    err.code = String(body.code);
+  }
+  return err;
+}
+var MetadataClient = class _MetadataClient {
+  constructor(config) {
+    __publicField(this, "base");
+    __publicField(this, "fetchImpl");
+    __publicField(this, "headers");
+    this.base = buildBase(config);
+    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.headers = { Accept: "application/json", ...config.headers ?? {} };
+  }
+  /** Update the client's environment scope at runtime. */
+  withEnvironment(environmentId) {
+    return new _MetadataClient({
+      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
+      environmentId,
+      fetch: this.fetchImpl,
+      headers: this.headers
+    });
+  }
+  /** List all registered metadata types (returns the registry rows). */
+  async listTypes() {
+    const res = await this.fetchImpl(this.base, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.entries)) return data.entries;
+    if (data && Array.isArray(data.items)) return data.items;
+    if (data && Array.isArray(data.types)) {
+      return data.types.map((t) => ({ type: t }));
+    }
+    return [];
+  }
+  /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+  async list(type, options = {}) {
+    const qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}${qs}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.items)) {
+      return data.items;
+    }
+    return [];
+  }
+  /**
+   * Get a single metadata item. Returns the unwrapped item content
+   * (matching the framework REST handler which calls `res.json(item)`).
+   * Returns `null` on 404 to keep the call-site ergonomic.
+   */
+  async get(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) return null;
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+  /**
+   * Save (PUT) a metadata item. The framework accepts both the bare
+   * item payload and the `{ item: ... }` / `{ metadata: ... }`
+   * envelopes; we send bare for consistency.
+   */
+  async save(type, name, item, options = {}) {
+    const qs = options.force ? "?force=true" : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
+    };
+    if (options.ifMatch) headers["If-Match"] = options.ifMatch;
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify(item)
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+  /**
+   * Get the 3-state layered view of a metadata item (Phase 3a). Returns
+   * `code` (the artifact / fallback default), `overlay` (the saved
+   * customisation, if any), and `effective` (what the runtime sees).
+   */
+  async layered(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) {
+      return { code: null, overlay: null, overlayScope: null, effective: null };
+    }
+    if (!res.ok) throw await parseError(res);
+    const body = await res.json();
+    const hasEnvelope = body && ("code" in body || "overlay" in body || "effective" in body);
+    if (!hasEnvelope) {
+      return {
+        code: null,
+        overlay: null,
+        overlayScope: null,
+        effective: body
+      };
+    }
+    return {
+      code: body.code ?? null,
+      overlay: body.overlay ?? null,
+      overlayScope: body.overlayScope ?? null,
+      effective: body.effective ?? null
+    };
+  }
+  /**
+   * Find every metadata item that references this one (Phase 3a). Useful
+   * for pre-delete impact analysis: "Are any views pointing at this
+   * object before I drop it?".
+   */
+  async references(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/references`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) return [];
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    return Array.isArray(data) ? data : data?.items ?? [];
+  }
+  /**
+   * Reset a metadata customization overlay back to the artifact default.
+   * Idempotent: returns the result even when no overlay row existed.
+   */
+  async reset(type, name, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    const headers = { ...this.headers };
+    if (options.ifMatch) headers["If-Match"] = options.ifMatch;
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, { method: "DELETE", headers });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+  /** Fetch the durable history (change log) for one metadata item. */
+  async history(type, name, options = {}) {
+    const params = new URLSearchParams();
+    if (options.sinceSeq !== void 0) params.set("sinceSeq", String(options.sinceSeq));
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/history${qs ? `?${qs}` : ""}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+};
+
 // src/security.ts
 var SecurityManager = class {
   constructor(policy = {}) {
@@ -2342,6 +2524,7 @@ function createObjectStackAdapter(config) {
   ConcurrentUpdateError,
   ConnectionError,
   IntegrationManager,
+  MetadataClient,
   MetadataNotFoundError,
   ObjectStackAdapter,
   ObjectStackError,

package/dist/index.d.cts

@@ -491,6 +491,162 @@ declare class IntegrationManager {
     private send;
 }
 
+/**
+ * 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.
+ */
+/**
+ * MetadataClient
+ *
+ * Thin, framework-agnostic HTTP client for the ObjectStack metadata
+ * API (`/api/v1/meta/*`). Used by the platform Setup app surfaces in
+ * `@object-ui/plugin-designer` (Object Manager, Field Designer, etc.)
+ * so they can read and write protocol metadata without depending on
+ * `ObjectStackAdapter` (which is a generic data-source binding and
+ * carries a lot of view/dashboard-specific behaviour we don't need
+ * here).
+ *
+ * Endpoints (see `packages/rest/src/rest-server.ts`):
+ *   GET    /api/v1/meta                  — list all metadata types
+ *   GET    /api/v1/meta/:type            — list items of a type
+ *   GET    /api/v1/meta/:type/:name      — get one item (returns the
+ *                                          unwrapped item content)
+ *   PUT    /api/v1/meta/:type/:name      — save (overlay) one item
+ *                                          honours `If-Match` for OCC
+ *   DELETE /api/v1/meta/:type/:name      — reset overlay to artifact
+ *   GET    /api/v1/meta/:type/:name/history — durable change log
+ *
+ * The client deliberately keeps the response shape opaque (typed as
+ * `unknown`/generic `T`) so callers explicitly narrow per-metadata-
+ * type, mirroring the framework's "single Zod source per type" rule.
+ */
+interface MetadataClientConfig {
+    /** Base URL of the ObjectStack server (no trailing slash needed). */
+    baseUrl: string;
+    /**
+     * Optional environment ID to scope reads/writes to a tenant. When
+     * provided, requests use the scoped path
+     * `/api/v1/environments/:environmentId/meta/...` and overlays are
+     * persisted in the environment's own metadata store.
+     */
+    environmentId?: string;
+    /** Optional custom fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof fetch;
+    /** Additional headers (e.g. auth) included on every request. */
+    headers?: Record<string, string>;
+}
+interface MetadataListOptions {
+    /** Filter by source package id (matches the `package` query param). */
+    packageId?: string;
+}
+interface MetadataSaveOptions {
+    /**
+     * Optimistic concurrency token (the `checksum` returned by the last
+     * read). When present, sent as the `If-Match` header so concurrent
+     * edits get a 409 instead of overwriting each other.
+     */
+    ifMatch?: string;
+    /** Optional actor id, sent as `X-Actor` for history attribution. */
+    actor?: string;
+    /**
+     * Bypass destructive-change protection (Phase 3a). The server returns
+     * `409 destructive_change` with `issues[]` if a write would drop or
+     * narrow data; setting `force: true` adds `?force=true` to the request
+     * so the operator can confirm and proceed.
+     */
+    force?: boolean;
+}
+/** Layered view of a metadata item — Phase 3a `?layers=true`. */
+interface MetadataLayered<T = unknown> {
+    /** Code-level (artifact) item; null if the item only exists as an overlay. */
+    code: T | null;
+    /** Org/environment overlay (just the saved delta or full overlay row). */
+    overlay: T | null;
+    /** Overlay scope (`organization` | `environment` | `package` | null). */
+    overlayScope: string | null;
+    /** Merged effective view — what the runtime actually sees. */
+    effective: T | null;
+}
+/** Reference back-pointer — Phase 3a `/references`. */
+interface MetadataReference {
+    /** Referencing item's metadata type. */
+    fromType: string;
+    /** Referencing item's name. */
+    fromName: string;
+    /** JSON path within the referencing item that holds the reference. */
+    path: string;
+    /** The actual value seen at `path` (the referenced name). */
+    value: string;
+}
+interface MetadataHistoryOptions {
+    /** Only return events after this sequence number. */
+    sinceSeq?: number;
+    /** Limit the number of events returned. */
+    limit?: number;
+}
+interface MetadataError extends Error {
+    status: number;
+    code?: string;
+    body?: unknown;
+}
+/**
+ * MetadataClient — read/write protocol metadata via the framework REST API.
+ *
+ * @example
+ * ```ts
+ * const client = new MetadataClient({ baseUrl: 'http://localhost:3000' });
+ * const objects = await client.list<{ name: string; label?: string }>('object');
+ * const account = await client.get<{ fields: Record<string, unknown> }>('object', 'account');
+ * await client.save('object', 'account', { ...account, label: 'Customer' });
+ * ```
+ */
+declare class MetadataClient {
+    private readonly base;
+    private readonly fetchImpl;
+    private readonly headers;
+    constructor(config: MetadataClientConfig);
+    /** Update the client's environment scope at runtime. */
+    withEnvironment(environmentId: string | undefined): MetadataClient;
+    /** List all registered metadata types (returns the registry rows). */
+    listTypes(): Promise<unknown[]>;
+    /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+    list<T = unknown>(type: string, options?: MetadataListOptions): Promise<T[]>;
+    /**
+     * Get a single metadata item. Returns the unwrapped item content
+     * (matching the framework REST handler which calls `res.json(item)`).
+     * Returns `null` on 404 to keep the call-site ergonomic.
+     */
+    get<T = unknown>(type: string, name: string): Promise<T | null>;
+    /**
+     * Save (PUT) a metadata item. The framework accepts both the bare
+     * item payload and the `{ item: ... }` / `{ metadata: ... }`
+     * envelopes; we send bare for consistency.
+     */
+    save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataSaveOptions): Promise<T>;
+    /**
+     * Get the 3-state layered view of a metadata item (Phase 3a). Returns
+     * `code` (the artifact / fallback default), `overlay` (the saved
+     * customisation, if any), and `effective` (what the runtime sees).
+     */
+    layered<T = unknown>(type: string, name: string): Promise<MetadataLayered<T>>;
+    /**
+     * Find every metadata item that references this one (Phase 3a). Useful
+     * for pre-delete impact analysis: "Are any views pointing at this
+     * object before I drop it?".
+     */
+    references(type: string, name: string): Promise<MetadataReference[]>;
+    /**
+     * Reset a metadata customization overlay back to the artifact default.
+     * Idempotent: returns the result even when no overlay row existed.
+     */
+    reset<T = unknown>(type: string, name: string, options?: MetadataSaveOptions): Promise<T>;
+    /** Fetch the durable history (change log) for one metadata item. */
+    history<T = unknown>(type: string, name: string, options?: MetadataHistoryOptions): Promise<T>;
+}
+
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -1233,4 +1389,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, MetadataNotFoundError, 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, MetadataClient, type MetadataClientConfig, type MetadataError, 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 };

package/dist/index.d.ts

@@ -491,6 +491,162 @@ declare class IntegrationManager {
     private send;
 }
 
+/**
+ * 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.
+ */
+/**
+ * MetadataClient
+ *
+ * Thin, framework-agnostic HTTP client for the ObjectStack metadata
+ * API (`/api/v1/meta/*`). Used by the platform Setup app surfaces in
+ * `@object-ui/plugin-designer` (Object Manager, Field Designer, etc.)
+ * so they can read and write protocol metadata without depending on
+ * `ObjectStackAdapter` (which is a generic data-source binding and
+ * carries a lot of view/dashboard-specific behaviour we don't need
+ * here).
+ *
+ * Endpoints (see `packages/rest/src/rest-server.ts`):
+ *   GET    /api/v1/meta                  — list all metadata types
+ *   GET    /api/v1/meta/:type            — list items of a type
+ *   GET    /api/v1/meta/:type/:name      — get one item (returns the
+ *                                          unwrapped item content)
+ *   PUT    /api/v1/meta/:type/:name      — save (overlay) one item
+ *                                          honours `If-Match` for OCC
+ *   DELETE /api/v1/meta/:type/:name      — reset overlay to artifact
+ *   GET    /api/v1/meta/:type/:name/history — durable change log
+ *
+ * The client deliberately keeps the response shape opaque (typed as
+ * `unknown`/generic `T`) so callers explicitly narrow per-metadata-
+ * type, mirroring the framework's "single Zod source per type" rule.
+ */
+interface MetadataClientConfig {
+    /** Base URL of the ObjectStack server (no trailing slash needed). */
+    baseUrl: string;
+    /**
+     * Optional environment ID to scope reads/writes to a tenant. When
+     * provided, requests use the scoped path
+     * `/api/v1/environments/:environmentId/meta/...` and overlays are
+     * persisted in the environment's own metadata store.
+     */
+    environmentId?: string;
+    /** Optional custom fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof fetch;
+    /** Additional headers (e.g. auth) included on every request. */
+    headers?: Record<string, string>;
+}
+interface MetadataListOptions {
+    /** Filter by source package id (matches the `package` query param). */
+    packageId?: string;
+}
+interface MetadataSaveOptions {
+    /**
+     * Optimistic concurrency token (the `checksum` returned by the last
+     * read). When present, sent as the `If-Match` header so concurrent
+     * edits get a 409 instead of overwriting each other.
+     */
+    ifMatch?: string;
+    /** Optional actor id, sent as `X-Actor` for history attribution. */
+    actor?: string;
+    /**
+     * Bypass destructive-change protection (Phase 3a). The server returns
+     * `409 destructive_change` with `issues[]` if a write would drop or
+     * narrow data; setting `force: true` adds `?force=true` to the request
+     * so the operator can confirm and proceed.
+     */
+    force?: boolean;
+}
+/** Layered view of a metadata item — Phase 3a `?layers=true`. */
+interface MetadataLayered<T = unknown> {
+    /** Code-level (artifact) item; null if the item only exists as an overlay. */
+    code: T | null;
+    /** Org/environment overlay (just the saved delta or full overlay row). */
+    overlay: T | null;
+    /** Overlay scope (`organization` | `environment` | `package` | null). */
+    overlayScope: string | null;
+    /** Merged effective view — what the runtime actually sees. */
+    effective: T | null;
+}
+/** Reference back-pointer — Phase 3a `/references`. */
+interface MetadataReference {
+    /** Referencing item's metadata type. */
+    fromType: string;
+    /** Referencing item's name. */
+    fromName: string;
+    /** JSON path within the referencing item that holds the reference. */
+    path: string;
+    /** The actual value seen at `path` (the referenced name). */
+    value: string;
+}
+interface MetadataHistoryOptions {
+    /** Only return events after this sequence number. */
+    sinceSeq?: number;
+    /** Limit the number of events returned. */
+    limit?: number;
+}
+interface MetadataError extends Error {
+    status: number;
+    code?: string;
+    body?: unknown;
+}
+/**
+ * MetadataClient — read/write protocol metadata via the framework REST API.
+ *
+ * @example
+ * ```ts
+ * const client = new MetadataClient({ baseUrl: 'http://localhost:3000' });
+ * const objects = await client.list<{ name: string; label?: string }>('object');
+ * const account = await client.get<{ fields: Record<string, unknown> }>('object', 'account');
+ * await client.save('object', 'account', { ...account, label: 'Customer' });
+ * ```
+ */
+declare class MetadataClient {
+    private readonly base;
+    private readonly fetchImpl;
+    private readonly headers;
+    constructor(config: MetadataClientConfig);
+    /** Update the client's environment scope at runtime. */
+    withEnvironment(environmentId: string | undefined): MetadataClient;
+    /** List all registered metadata types (returns the registry rows). */
+    listTypes(): Promise<unknown[]>;
+    /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+    list<T = unknown>(type: string, options?: MetadataListOptions): Promise<T[]>;
+    /**
+     * Get a single metadata item. Returns the unwrapped item content
+     * (matching the framework REST handler which calls `res.json(item)`).
+     * Returns `null` on 404 to keep the call-site ergonomic.
+     */
+    get<T = unknown>(type: string, name: string): Promise<T | null>;
+    /**
+     * Save (PUT) a metadata item. The framework accepts both the bare
+     * item payload and the `{ item: ... }` / `{ metadata: ... }`
+     * envelopes; we send bare for consistency.
+     */
+    save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataSaveOptions): Promise<T>;
+    /**
+     * Get the 3-state layered view of a metadata item (Phase 3a). Returns
+     * `code` (the artifact / fallback default), `overlay` (the saved
+     * customisation, if any), and `effective` (what the runtime sees).
+     */
+    layered<T = unknown>(type: string, name: string): Promise<MetadataLayered<T>>;
+    /**
+     * Find every metadata item that references this one (Phase 3a). Useful
+     * for pre-delete impact analysis: "Are any views pointing at this
+     * object before I drop it?".
+     */
+    references(type: string, name: string): Promise<MetadataReference[]>;
+    /**
+     * Reset a metadata customization overlay back to the artifact default.
+     * Idempotent: returns the result even when no overlay row existed.
+     */
+    reset<T = unknown>(type: string, name: string, options?: MetadataSaveOptions): Promise<T>;
+    /** Fetch the durable history (change log) for one metadata item. */
+    history<T = unknown>(type: string, name: string, options?: MetadataHistoryOptions): Promise<T>;
+}
+
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -1233,4 +1389,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, MetadataNotFoundError, 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, MetadataClient, type MetadataClientConfig, type MetadataError, 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 };