@object-ui/data-objectstack 6.2.3 → 7.1.0

package/dist/index.d.cts

@@ -537,11 +537,32 @@ interface MetadataClientConfig {
     fetch?: typeof fetch;
     /** Additional headers (e.g. auth) included on every request. */
     headers?: Record<string, string>;
+    /**
+     * ADR-0037 Live Canvas — render the world **as-if-published**. When true,
+     * `list()` and `get()` append `?preview=draft`, which the framework
+     * dispatcher maps to `getMetaItems/getMetaItem({ previewDrafts: true })`:
+     * pending ADR-0033 drafts overlay the active registry (draft wins by name,
+     * draft-only items surface). Reads only — writes are unaffected, and
+     * nothing the preview shows is live until Publish.
+     */
+    previewDrafts?: boolean;
 }
 interface MetadataListOptions {
     /** Filter by source package id (matches the `package` query param). */
     packageId?: string;
 }
+/**
+ * A pending DRAFT metadata item (ADR-0033), as returned by {@link MetadataClient.listDrafts}.
+ * Light header — no body — carrying the owning package so the console can group
+ * pending changes by app package.
+ */
+interface MetadataDraftHeader {
+    type: string;
+    name: string;
+    packageId: string | null;
+    updatedAt: string | null;
+    updatedBy: string | null;
+}
 interface MetadataSaveOptions {
     /**
      * Optimistic concurrency token (the `checksum` returned by the last
@@ -558,6 +579,42 @@ interface MetadataSaveOptions {
      * so the operator can confirm and proceed.
      */
     force?: boolean;
+    /**
+     * Save mode — `'draft'` writes a pending draft row (invisible to the
+     * runtime until `publish()` is called); `'publish'` writes directly
+     * to the active overlay. Omit (or set `'publish'`) for the legacy
+     * "save = live" behaviour.
+     */
+    mode?: 'draft' | 'publish';
+    /**
+     * Software-package id to bind the saved row to (sent as the `package`
+     * query param → `sys_metadata.package_id`). Set when authoring inside a
+     * Studio package workspace. Omit for an env-local overlay.
+     */
+    packageId?: string;
+}
+interface MetadataGetOptions {
+    /**
+     * Read a specific overlay state. `'draft'` returns the pending draft
+     * body (no fallback to the published overlay or the registry); omit
+     * to read the active (published) value.
+     */
+    state?: 'active' | 'draft';
+    /**
+     * Software-package id to scope resolution (sent as the `package` query
+     * param → server prefer-local, ADR-0048). Set when reading one item that
+     * may collide by name across installed packages (e.g. the Studio editor
+     * passes the edited item's owning package). Omit for context-free reads.
+     */
+    packageId?: string;
+}
+interface MetadataDeleteOptions extends MetadataSaveOptions {
+    /**
+     * Target state. `'draft'` discards the pending draft (keeps the
+     * published overlay intact). Omit to reset the active overlay back
+     * to the artifact default (the legacy behaviour).
+     */
+    state?: 'active' | 'draft';
 }
 /** Layered view of a metadata item — Phase 3a `?layers=true`. */
 interface MetadataLayered<T = unknown> {
@@ -569,6 +626,126 @@ interface MetadataLayered<T = unknown> {
     overlayScope: string | null;
     /** Merged effective view — what the runtime actually sees. */
     effective: T | null;
+    /**
+     * Load-time validation result for `effective` (server-computed via
+     * the same Zod registry used at save time). Undefined for types
+     * without a registered Zod schema. Surfaced by the Studio as a
+     * banner + inline field errors so operators can spot bad metadata
+     * without having to hit Save.
+     */
+    _diagnostics?: MetadataDiagnostics;
+    /** 4-state lock: `none` / `no-overlay` / `no-delete` / `full`. */
+    lock?: 'none' | 'no-overlay' | 'no-delete' | 'full';
+    /** Human-readable reason for the lock (tooltip text). */
+    lockReason?: string;
+    /** Which layer set the lock: artifact / package / overlay / env-forced. */
+    lockSource?: 'artifact' | 'package' | 'overlay' | 'env-forced';
+    /** Optional docs URL for the lock reason (rendered as "View docs →"). */
+    lockDocsUrl?: string;
+    /** Origin of the item: `package` (loader) | `org` (tenant) | `env-forced`. */
+    provenance?: 'package' | 'org' | 'env-forced';
+    /** Owning package id (denormalised from the loader tag). */
+    packageId?: string;
+    /** Owning package version. */
+    packageVersion?: string;
+    /** True when the editor should allow Save (PUT). */
+    editable?: boolean;
+    /** True when the editor should allow Delete. */
+    deletable?: boolean;
+    /** True when "Reset to package default" applies (has overlay + artifact). */
+    resettable?: boolean;
+}
+/**
+ * One row in the metadata protection-audit trail
+ * (ADR-0010 §3.6 / Phase 4.1). Mirrors `sys_metadata_audit` columns
+ * the API exposes.
+ */
+interface MetadataAuditEntry {
+    /** Stable audit-row id (uuid). */
+    id: unknown;
+    /** ISO timestamp when the attempt happened. */
+    occurredAt: string;
+    /** Who attempted the operation (`x-actor` header or `'system'`). */
+    actor: string;
+    /** Code path that recorded the row (e.g. `protocol.saveMetaItem`). */
+    source: string | null;
+    /** Which lifecycle op was attempted. */
+    operation: 'save' | 'publish' | 'rollback' | 'delete' | 'reset';
+    /** Decision: allowed / denied / forced (admin override). */
+    outcome: 'allowed' | 'denied' | 'forced';
+    /** Machine-readable reason code (`item_locked`, `ok`, …). */
+    code: string;
+    /** Effective lock at the moment of the attempt. */
+    lockState: 'none' | 'no-overlay' | 'no-delete' | 'full' | null;
+    /** True when admin forced the write through despite the lock. */
+    lockOverridden: boolean;
+    /** Request-id for trace correlation (if propagated). */
+    requestId: string | null;
+    /** Free-text note (often the lock reason). */
+    note: string | null;
+}
+/** Response shape for `MetadataClient.audit()`. */
+interface MetadataAuditResponse {
+    events: MetadataAuditEntry[];
+}
+/**
+ * Load-time validation envelope attached to metadata items by the
+ * framework. Mirrors `MetadataValidationResult` in the kernel spec.
+ */
+interface MetadataDiagnostics {
+    valid: boolean;
+    errors?: Array<{
+        path: string;
+        message: string;
+        code?: string;
+    }>;
+    warnings?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+/** Options for the cross-type `/meta/diagnostics` sweep call. */
+interface MetadataDiagnosticsOptions {
+    /** Restrict the sweep to a single metadata type (e.g. `'view'`). */
+    type?: string;
+    /**
+     * `'error'` (default) returns only items that fail validation.
+     * `'warning'` also includes items whose only diagnostics are warnings.
+     */
+    severity?: 'error' | 'warning';
+    /** Restrict to items owned by this package id. */
+    packageId?: string;
+}
+/** One row in the `/meta/diagnostics` response. */
+interface MetadataDiagnosticsEntry {
+    type: string;
+    name: string;
+    diagnostics: MetadataDiagnostics;
+}
+/** Top-level envelope returned by `/meta/diagnostics`. */
+interface MetadataDiagnosticsSummary {
+    entries: MetadataDiagnosticsEntry[];
+    /** Number of `entries` returned (post-filter). */
+    total: number;
+    /** How many metadata types the sweep visited. */
+    scannedTypes: number;
+    /** How many individual items were validated. */
+    scannedItems: number;
+    /**
+     * Per-type aggregate stats — count of items and the list of
+     * packages contributing to each type. Computed in the same sweep
+     * so a single call serves both the diagnostics governance page and
+     * the directory tile counts / package filter.
+     *
+     * Optional for backward compatibility with older framework
+     * versions that do not yet emit it; clients should fall back to
+     * an empty record.
+     */
+    stats?: Record<string, {
+        count: number;
+        locked?: number;
+        packages: string[];
+    }>;
 }
 /** Reference back-pointer — Phase 3a `/references`. */
 interface MetadataReference {
@@ -607,31 +784,101 @@ declare class MetadataClient {
     private readonly base;
     private readonly fetchImpl;
     private readonly headers;
+    /** ADR-0037: when true, reads render the draft-overlaid world. */
+    readonly previewDrafts: boolean;
     constructor(config: MetadataClientConfig);
     /** Update the client's environment scope at runtime. */
     withEnvironment(environmentId: string | undefined): MetadataClient;
+    /**
+     * Derive a client whose reads render the draft-overlaid world (or not).
+     * Same base/fetch/headers; used by the app-shell to switch the whole
+     * renderer tree into ADR-0037 preview mode off one URL flag.
+     */
+    withPreviewDrafts(previewDrafts: boolean): 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[]>;
+    /**
+     * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
+     * published yet. `list()` only sees published/active metadata, so a
+     * just-built app package looks empty there; this surfaces the drafts so the
+     * console can show a "pending changes" view and draft-aware package contents.
+     * Optionally narrow by `packageId` and/or `type`. Returns light headers
+     * (no body) carrying `packageId` for grouping.
+     */
+    listDrafts(options?: {
+        packageId?: string;
+        type?: string;
+    }): Promise<MetadataDraftHeader[]>;
     /**
      * 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>;
+    get<T = unknown>(type: string, name: string, options?: MetadataGetOptions): Promise<T | null>;
+    /**
+     * Read the pending draft body for an item (`?state=draft`). Returns
+     * `null` when there is no draft pending. Draft reads do NOT fall
+     * back to the published overlay or the artifact registry — a `null`
+     * unambiguously means "nothing to publish".
+     *
+     * Note: the framework wraps draft responses in an envelope
+     * `{ type, name, item }` (matching `getMetaItem`); callers should
+     * read `.item` to get the body. The legacy `get()` returns the
+     * unwrapped body, so this method preserves that asymmetry by
+     * returning whatever the server sent.
+     */
+    getDraft<T = unknown>(type: string, name: string, options?: {
+        packageId?: 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.
+     * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
+     * stage the change without publishing (Studio's "Save" button).
      */
     save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataSaveOptions): Promise<T>;
+    /**
+     * Publish a single pending draft BY REFERENCE — promotes the draft row for
+     * `(type, name)` into the active overlay and drops the draft. Works for ANY
+     * draft, including ones with no `packageId` binding (which the package-scoped
+     * `/packages/:id/publish-drafts` flow cannot reach). Use this to publish the
+     * exact set returned by {@link listDrafts} without needing a package.
+     *
+     * Returns the server result. For `seed` drafts the protocol also materializes
+     * the rows and reports under `seedApplied` — a data problem never fails the
+     * publish, so callers should check `seedApplied?.success` and warn the user
+     * rather than assume the data went live.
+     */
+    publishDraft(type: string, name: string): Promise<{
+        success?: boolean;
+        seedApplied?: {
+            success: boolean;
+            inserted?: number;
+            updated?: number;
+            error?: string;
+            errors?: unknown[];
+        };
+    } & Record<string, unknown>>;
     /**
      * 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>>;
+    layered<T = unknown>(type: string, name: string, options?: {
+        packageId?: string;
+    }): Promise<MetadataLayered<T>>;
+    /**
+     * Cross-type sweep of load-time validation results — calls
+     * `GET /meta/diagnostics`. Returns every entry the framework
+     * considers invalid (or, when `severity: 'warning'`, also entries
+     * with only warnings).
+     *
+     * Used by the Studio's governance overview page and by the
+     * directory page to show "N invalid" badges per metadata type.
+     */
+    diagnostics(options?: MetadataDiagnosticsOptions): Promise<MetadataDiagnosticsSummary>;
     /**
      * Find every metadata item that references this one (Phase 3a). Useful
      * for pre-delete impact analysis: "Are any views pointing at this
@@ -641,10 +888,53 @@ declare class MetadataClient {
     /**
      * Reset a metadata customization overlay back to the artifact default.
      * Idempotent: returns the result even when no overlay row existed.
+     * Pass `state: 'draft'` to discard the pending draft only (keeps the
+     * published overlay intact) — useful for a Studio "Discard draft" button.
+     */
+    reset<T = unknown>(type: string, name: string, options?: MetadataDeleteOptions): Promise<T>;
+    /**
+     * Promote the pending draft of an item to the active overlay
+     * (POST `/meta/:type/:name/publish`). Returns
+     * `{ success, version, seq, message }`. Throws a `404 no_draft` if
+     * nothing is pending and `409 metadata_conflict` if the published
+     * overlay moved while the draft was sitting.
+     */
+    publish<T = unknown>(type: string, name: string, options?: {
+        actor?: string;
+        message?: string;
+    }): Promise<T>;
+    /**
+     * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
+     * The server reads the history row at `toVersion`, writes its body back
+     * as the active overlay with `operation_type='revert'`. Returns
+     * `{ success, version, seq, restoredFromVersion, message }`. Throws
+     * `404 version_not_found` for unknown versions and `409 version_not_restorable`
+     * when the target version is a delete tombstone.
+     */
+    rollback<T = unknown>(type: string, name: string, toVersion: number, options?: {
+        actor?: string;
+        message?: string;
+    }): Promise<T>;
+    /**
+     * Compute a structured top-level key diff between two history versions
+     * (GET `/meta/:type/:name/diff?from=&to=`). Returns
+     * `{ added, removed, changed }` where each entry carries a `path` and
+     * the relevant value(s). Useful for "what changed in this draft?" and
+     * pre-rollback previews.
      */
-    reset<T = unknown>(type: string, name: string, options?: MetadataSaveOptions): Promise<T>;
+    diff<T = unknown>(type: string, name: string, fromVersion?: number, toVersion?: number): Promise<T>;
     /** Fetch the durable history (change log) for one metadata item. */
     history<T = unknown>(type: string, name: string, options?: MetadataHistoryOptions): Promise<T>;
+    /**
+     * Fetch the protection-audit trail for one metadata item
+     * (ADR-0010 §3.6 / Phase 4.1). Shows every save/publish/rollback/
+     * delete/reset attempt — allowed, denied, or forced — so the
+     * Studio "审计日志 / Audit log" tab can render who tried what
+     * and whether a lock blocked it.
+     */
+    audit(type: string, name: string, options?: {
+        limit?: number;
+    }): Promise<MetadataAuditResponse>;
 }
 
 /**
@@ -1127,6 +1417,20 @@ declare 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).
+     */
+    batchTransaction(operations: Array<{
+        object: string;
+        action?: 'create' | 'update' | 'delete';
+        data?: any;
+        id?: string;
+    }>): Promise<{
+        results: any[];
+    }>;
     bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
     /**
      * Normalize the result from data.find() or data.query() into a consistent QueryResult.
@@ -1152,6 +1456,24 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to the object schema
      */
     getObjectSchema(objectName: string): Promise<unknown>;
+    /**
+     * 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 fetchObjectSchemaFresh;
     /**
      * Get access to the underlying ObjectStack client for advanced operations.
      */
@@ -1286,6 +1608,65 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * is not available.
      */
     aggregate(resource: string, params: any): Promise<any[]>;
+    /**
+     * 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.
+     */
+    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>>;
+        }>;
+    }>;
     /** Client-side aggregation fallback */
     private aggregateClientSide;
     /**
@@ -1389,4 +1770,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, 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 };
+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 };