@proteos/sdk 0.51.0 → 0.52.0

package/src/meta/types.ts

@@ -1,6 +1,12 @@
 import { z } from 'zod'
 import type { AuditFields, ListOptions } from '../types/common.js'
 import { AuditFieldsSchema } from '../types/common.js'
+import {
+  type LayoutElement,
+  LayoutElementSchema,
+  type LayoutTab,
+  LayoutTabSchema,
+} from './layout/elements.js'
 import { type PageLayout, PageLayoutSchema } from './layout/page-layout.js'
 
 export type { PageLayout } from './layout/page-layout.js'
@@ -368,6 +374,13 @@ export interface Attribute {
    * Mirrors `IsPlatformManaged` in the Go `metamodel.Attribute`.
    */
   is_platform_managed?: boolean
+  /**
+   * Server-stamped back-reference to the entity extension that contributes
+   * this attribute to its host entity. Present only on a host's merged
+   * attribute list; ignored (stripped and re-derived) on writes. Mirrors
+   * `ExtensionKey` in the Go `metamodel.Attribute`.
+   */
+  extension_key?: string
   /**
    * Attribute-level permissions. Absent means unrestricted (today's behaviour).
    * Platform-managed attributes cannot carry restrictions.
@@ -485,6 +498,7 @@ export const AttributeSchema = z.object({
   is_nullable: z.boolean().optional(),
   is_unique: z.boolean(),
   is_read_only: z.boolean().optional(),
+  extension_key: z.string().optional(),
   restrictions: AttributeRestrictionsSchema.optional(),
   default_value: z.unknown().optional(),
   meta: z.unknown().optional(),
@@ -882,6 +896,12 @@ export interface Column {
   attribute: string
   label: string
   width: number
+  /**
+   * Server-stamped back-reference to the list extension that contributes this
+   * column to its host list. Present only on a host's merged column list;
+   * ignored (stripped and re-derived) on writes.
+   */
+  extension_key?: string
 }
 
 /**
@@ -948,6 +968,8 @@ export interface PageAction {
   params?: Record<string, string>
   inputs?: Record<string, string>
   skip_confirmation?: boolean
+  /** List-extension stamp on a toolbar action a list extension appended to its host list. */
+  extension_key?: string
 }
 
 export const PageActionSchema = z.object({
@@ -959,6 +981,7 @@ export const PageActionSchema = z.object({
   params: z.record(z.string()).optional(),
   inputs: z.record(z.string()).optional(),
   skip_confirmation: z.boolean().optional(),
+  extension_key: z.string().optional(),
 })
 
 /**
@@ -1002,6 +1025,7 @@ export const ColumnSchema = z.object({
   attribute: z.string(),
   label: z.string(),
   width: z.number(),
+  extension_key: z.string().optional(),
 })
 
 export const SortConfigSchema = z.object({
@@ -1250,6 +1274,7 @@ export type MenuItemType = (typeof MenuItemType)[keyof typeof MenuItemType]
  * Menu item definition. Matches the backend JSON shape for nested menus.
  */
 export interface MenuItem {
+  /** Stable within the menu; the menu's extension API (menu-configuration extensions anchor on it). */
   id: string
   order: number
   label: string
@@ -1257,6 +1282,12 @@ export interface MenuItem {
   icon: string
   reference?: string
   children: MenuItem[] | null
+  /** Server stamp: the item was contributed by this menu-configuration extension. Never authored. */
+  extension_key?: string
+  /** Server stamp: a `remove` tombstone — consumers skip the item. Never authored. */
+  is_hidden?: boolean
+  /** Server stamp: the host's own item this stamped item displaced (`replace` / `remove`). Never authored. */
+  replaced_item?: MenuItem
 }
 
 /**
@@ -1280,6 +1311,9 @@ export const MenuItemSchema = z.lazy(() =>
     icon: z.string(),
     reference: z.string().optional(),
     children: z.array(MenuItemSchema).nullable(),
+    extension_key: z.string().optional(),
+    is_hidden: z.boolean().optional(),
+    replaced_item: z.lazy(() => MenuItemSchema).optional(),
   }),
 ) as unknown as z.ZodType<MenuItem>
 
@@ -1325,6 +1359,370 @@ export interface UpdateMenuConfigurationRequest {
   is_default?: boolean
 }
 
+// ============================================================================
+// EntityExtension Types
+// ============================================================================
+
+/**
+ * EntityExtension — attributes contributed to ONE existing host entity by a
+ * resource that does not own it (typically a second module). The host's
+ * `attributes` are the materialized merge: its own attributes plus every
+ * extension's, each stamped with `extension_key`. The row itself stores the
+ * author's list unstamped. `key` is the identity; `entity_slug` is immutable
+ * after create (delete and recreate to re-host).
+ */
+export interface EntityExtension extends AuditFields {
+  key: string
+  org_id: string
+  name: string
+  description: string
+  /** The host entity the attributes are merged into. */
+  entity_slug: string
+  module_slug: string
+  /** The contributed definitions, exactly as authored (no `extension_key`). */
+  attributes: Attribute[]
+}
+
+export const EntityExtensionSchema = AuditFieldsSchema.extend({
+  key: z.string(),
+  org_id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  entity_slug: z.string(),
+  module_slug: z.string(),
+  attributes: z.array(AttributeSchema),
+})
+
+export interface ListEntityExtensionsOptions extends MetaListOptions {
+  key?: string
+  name?: string
+  entity_slug?: string
+  module_slug?: string
+}
+
+/**
+ * Request to create an entity extension: at least one attribute, no platform
+ * attribute names, no `extension_key` (the server stamps it on the host).
+ */
+export interface CreateEntityExtensionRequest {
+  key: string
+  name?: string
+  description?: string
+  entity_slug: string
+  module_slug?: string
+  attributes: Attribute[]
+}
+
+/**
+ * Partial update. `attributes`, when present, replaces the whole contributed
+ * list. `entity_slug` is immutable — delete and recreate to re-host.
+ */
+export interface UpdateEntityExtensionRequest {
+  name?: string
+  description?: string
+  module_slug?: string
+  attributes?: Attribute[]
+}
+
+// ============================================================================
+// PageExtension Types
+// ============================================================================
+
+/**
+ * Where a placement's block goes relative to its anchor. `first` / `last`
+ * mean "inside this container", `before` / `after` mean "next to this node"
+ * (a sibling of the same kind: element next to element, tab next to tab).
+ */
+export type ExtensionPosition = 'before' | 'after' | 'first' | 'last'
+
+export const ExtensionPositionSchema = z.enum(['before', 'after', 'first', 'last'])
+
+/**
+ * Virtual anchors naming the layout roots (`first` / `last` only). Dots keep
+ * them out of the kebab-case authored-id namespace.
+ */
+export const PAGE_EXTENSION_ANCHOR_MAIN = 'layout.main'
+export const PAGE_EXTENSION_ANCHOR_SIDE_PANEL = 'layout.side_panel'
+
+/**
+ * One anchored block: the anchor (an element id, a tab id, or a virtual root
+ * anchor) in the host's OWN layout, a position, and the payload. Exactly one
+ * of `elements` / `tabs` is set; which one is right follows from the anchor —
+ * a tabs element (`first` / `last`) or a tab id (`before` / `after`) takes
+ * `tabs`, everything else takes `elements`. The payload lands as ONE
+ * contiguous run in author order. Every element and tab needs an authored id.
+ */
+export interface PageExtensionPlacement {
+  anchor_id: string
+  position: ExtensionPosition
+  elements?: LayoutElement[]
+  tabs?: LayoutTab[]
+}
+
+export const PageExtensionPlacementSchema = z.object({
+  anchor_id: z.string().min(1),
+  position: ExtensionPositionSchema,
+  elements: z.array(LayoutElementSchema).optional(),
+  tabs: z.array(LayoutTabSchema).optional(),
+})
+
+/**
+ * PageExtension — anchored layout blocks contributed to ONE existing host page
+ * by a resource that does not own it (typically a second module). The host's
+ * `layout` is the materialized merge: its own tree plus every extension's
+ * placements, each contributed element and tab stamped with `extension_key`.
+ * The row itself stores the author's placements unstamped. `key` is the
+ * identity; `page_slug` is immutable after create (delete and recreate to
+ * re-host).
+ */
+export interface PageExtension extends AuditFields {
+  key: string
+  org_id: string
+  name: string
+  description: string
+  /** The host page the placements are merged into. */
+  page_slug: string
+  module_slug: string
+  /** The contributed blocks, exactly as authored (no `extension_key`). */
+  placements: PageExtensionPlacement[]
+}
+
+export const PageExtensionSchema = AuditFieldsSchema.extend({
+  key: z.string(),
+  org_id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  page_slug: z.string(),
+  module_slug: z.string(),
+  placements: z.array(PageExtensionPlacementSchema),
+})
+
+export interface ListPageExtensionsOptions extends MetaListOptions {
+  key?: string
+  name?: string
+  page_slug?: string
+  module_slug?: string
+}
+
+/**
+ * Request to create a page extension: at least one placement, an authored id
+ * on every contributed element and tab, no `extension_key` (the server stamps
+ * it on the host).
+ */
+export interface CreatePageExtensionRequest {
+  key: string
+  name?: string
+  description?: string
+  page_slug: string
+  module_slug?: string
+  placements: PageExtensionPlacement[]
+}
+
+/**
+ * Partial update. `placements`, when present, replaces the whole contributed
+ * list. `page_slug` is immutable — delete and recreate to re-host.
+ */
+export interface UpdatePageExtensionRequest {
+  name?: string
+  description?: string
+  module_slug?: string
+  placements?: PageExtensionPlacement[]
+}
+
+// ============================================================================
+// MenuConfigurationExtension Types
+// ============================================================================
+
+/**
+ * Where a menu placement's block goes relative to its anchor. The four insert
+ * positions are the shared `ExtensionPosition`; `replace` swaps the anchor
+ * (whole subtree) for the block, `remove` hides it. Both keep the host's
+ * original under `replaced_item` on the materialized tree.
+ */
+export type MenuConfigurationExtensionPosition = ExtensionPosition | 'replace' | 'remove'
+
+export const MenuConfigurationExtensionPositionSchema = z.enum([
+  'before',
+  'after',
+  'first',
+  'last',
+  'replace',
+  'remove',
+])
+
+/** Virtual anchor naming the menu's root item list (`first` / `last` only). */
+export const MENU_CONFIGURATION_EXTENSION_ANCHOR_ITEMS = 'menu.items'
+
+/**
+ * One anchored block: the anchor (an item id in the host's OWN tree, or the
+ * virtual root `menu.items`), a position, and the contributed items (one
+ * contiguous run in author order). `remove` carries no items; every other
+ * position needs at least one. `first` / `last` on an item go into its
+ * children (groups only). Every contributed item needs an authored id.
+ */
+export interface MenuConfigurationExtensionPlacement {
+  anchor_id: string
+  position: MenuConfigurationExtensionPosition
+  items?: MenuItem[]
+}
+
+export const MenuConfigurationExtensionPlacementSchema = z.object({
+  anchor_id: z.string().min(1),
+  position: MenuConfigurationExtensionPositionSchema,
+  items: z.array(MenuItemSchema).optional(),
+})
+
+/**
+ * MenuConfigurationExtension — items contributed to ONE existing host menu
+ * configuration by a resource that does not own it (typically a second
+ * module). The host's `items` are the materialized merge: its own tree plus
+ * every extension's placements, each contributed item stamped with
+ * `extension_key` (a replaced / removed host item kept under `replaced_item`).
+ * The row itself stores the author's placements unstamped. `key` is the
+ * identity; `menu_slug` is immutable after create (delete and recreate to
+ * re-host).
+ */
+export interface MenuConfigurationExtension extends AuditFields {
+  key: string
+  org_id: string
+  name: string
+  description: string
+  /** The host menu configuration the placements are merged into. */
+  menu_slug: string
+  module_slug: string
+  /** The contributed blocks, exactly as authored (no `extension_key`). */
+  placements: MenuConfigurationExtensionPlacement[]
+}
+
+export const MenuConfigurationExtensionSchema = AuditFieldsSchema.extend({
+  key: z.string(),
+  org_id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  menu_slug: z.string(),
+  module_slug: z.string(),
+  placements: z.array(MenuConfigurationExtensionPlacementSchema),
+})
+
+export interface ListMenuConfigurationExtensionsOptions extends MetaListOptions {
+  key?: string
+  name?: string
+  menu_slug?: string
+  module_slug?: string
+}
+
+/**
+ * Request to create a menu-configuration extension: at least one placement,
+ * an authored id on every contributed item, no `extension_key` (the server
+ * stamps it on the host).
+ */
+export interface CreateMenuConfigurationExtensionRequest {
+  key: string
+  name?: string
+  description?: string
+  menu_slug: string
+  module_slug?: string
+  placements: MenuConfigurationExtensionPlacement[]
+}
+
+/**
+ * Partial update. `placements`, when present, replaces the whole contributed
+ * list. `menu_slug` is immutable — delete and recreate to re-host.
+ */
+export interface UpdateMenuConfigurationExtensionRequest {
+  name?: string
+  description?: string
+  module_slug?: string
+  placements?: MenuConfigurationExtensionPlacement[]
+}
+
+// ============================================================================
+// ListExtension Types
+// ============================================================================
+
+/**
+ * One anchored run of columns. `anchor_attribute` names a column of the host's
+ * OWN column list by its attribute path (a column's identity); required for
+ * `before` / `after`, must be empty for `first` / `last` (the ends of the
+ * list). The columns land as one contiguous run in author order.
+ */
+export interface ListExtensionColumnPlacement {
+  anchor_attribute?: string
+  position: ExtensionPosition
+  columns: Column[]
+}
+
+export const ListExtensionColumnPlacementSchema = z.object({
+  anchor_attribute: z.string().optional(),
+  position: ExtensionPositionSchema,
+  columns: z.array(ColumnSchema).min(1),
+})
+
+/**
+ * ListExtension — columns and toolbar actions contributed to ONE existing host
+ * list by a resource that does not own it. The host's `columns` / `actions`
+ * are the materialized merge, each contributed one stamped `extension_key`;
+ * the row stores the author's payload unstamped. `key` is the identity;
+ * `list_slug` is immutable after create. Sorting, filters and selection mode
+ * stay the owner's.
+ */
+export interface ListExtension extends AuditFields {
+  key: string
+  org_id: string
+  name: string
+  description: string
+  /** The host list the columns and actions are merged into. */
+  list_slug: string
+  module_slug: string
+  columns: ListExtensionColumnPlacement[]
+  /** Appended after the host's own toolbar actions (no anchor). */
+  actions: PageAction[]
+}
+
+export const ListExtensionSchema = AuditFieldsSchema.extend({
+  key: z.string(),
+  org_id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  list_slug: z.string(),
+  module_slug: z.string(),
+  columns: z.array(ListExtensionColumnPlacementSchema),
+  actions: z.array(PageActionSchema),
+})
+
+export interface ListListExtensionsOptions extends MetaListOptions {
+  key?: string
+  name?: string
+  list_slug?: string
+  module_slug?: string
+}
+
+/**
+ * Request to create a list extension: at least one column placement or
+ * action, no `extension_key` (the server stamps it on the host).
+ */
+export interface CreateListExtensionRequest {
+  key: string
+  name?: string
+  description?: string
+  list_slug: string
+  module_slug?: string
+  columns?: ListExtensionColumnPlacement[]
+  actions?: PageAction[]
+}
+
+/**
+ * Partial update. `columns` / `actions`, when present, each replace their
+ * whole list. `list_slug` is immutable — delete and recreate to re-host.
+ */
+export interface UpdateListExtensionRequest {
+  name?: string
+  description?: string
+  module_slug?: string
+  columns?: ListExtensionColumnPlacement[]
+  actions?: PageAction[]
+}
+
 // ============================================================================
 // AppConfiguration Types
 // ============================================================================