@proteos/sdk 0.51.1 → 0.53.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'
@@ -42,6 +48,7 @@ export type AttributeType =
   | 'currency'
   | 'knowledge-text'
   | 'file'
+  | 'contact-address'
 
 /**
  * Attribute-level permissions: restricting a FIELD rather than a record — a
@@ -281,6 +288,32 @@ export const CurrencyAttributeMetaSchema = z.object({
   allowed_currency_codes: z.array(z.string()).optional(),
 })
 
+/**
+ * Which endpoint a `contact-address` attribute holds. The record-capable
+ * subset of the conversation contact-address kinds — what a human types.
+ */
+export type ContactAddressAttributeKind = 'email' | 'phone' | 'linkedin_public_identifier'
+
+/**
+ * Metadata for a `contact-address`-typed attribute: ONE canonical reachable
+ * address of the person the record represents. The stored value is a plain
+ * string canonicalized on write (lowercased email, E.164 phone with a leading
+ * `+`, LinkedIn public identifier — a pasted profile URL is reduced to its
+ * `/in/<slug>`; displayed as https://www.linkedin.com/in/<slug>; LinkedIn
+ * profile ids such as ACoAA… are refused — the platform learns them itself).
+ * Records carrying such values bind to exactly one conversation contact;
+ * `kind` is REQUIRED. Mirror of the Go `metamodel.ContactAddressAttributeMeta`.
+ */
+export interface ContactAddressAttributeMeta {
+  kind: ContactAddressAttributeKind
+  description?: string
+}
+
+export const ContactAddressAttributeMetaSchema = z.object({
+  kind: z.enum(['email', 'phone', 'linkedin_public_identifier']),
+  description: z.string().optional(),
+})
+
 /**
  * The value of a `knowledge-text`-typed attribute: a reference to the
  * knowledge node (knowledge-service) that owns the text body. The record
@@ -348,6 +381,7 @@ export type AttributeMeta =
   | CurrencyAttributeMeta
   | KnowledgeTextAttributeMeta
   | FileAttributeMeta
+  | ContactAddressAttributeMeta
 
 /**
  * Entity attribute definition. Mirrors `model.Attribute` in the Go SDK.
@@ -368,6 +402,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 +526,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(),
@@ -558,6 +600,18 @@ export function parseFileMeta(attr: Attribute): FileAttributeMeta | null {
   return parsed.success ? parsed.data : {}
 }
 
+/**
+ * Returns the typed `ContactAddressAttributeMeta` when `attr` is a
+ * contact-address attribute with a valid kind; null otherwise. Unlike the
+ * `{}`-defaulting parsers, `kind` is required — an attribute without one
+ * cannot be canonicalized, so it resolves to null (shape of parseRelationMeta).
+ */
+export function parseContactAddressMeta(attr: Attribute): ContactAddressAttributeMeta | null {
+  if (attr.type !== 'contact-address') return null
+  const parsed = ContactAddressAttributeMetaSchema.safeParse(attr.meta)
+  return parsed.success ? parsed.data : null
+}
+
 /**
  * A single operation a resource may be publicly exposed for. Independent set
  * (not a level): a resource can be public for `write` without `read`. Only
@@ -571,6 +625,27 @@ export const PublicAccessOperationSchema = z.enum(['read', 'write', 'delete'])
  * Entity definition.
  * Note: Entity uses `slug` as its primary identifier, not `id`.
  */
+/**
+ * What happens when a record's contact-address value already belongs to a
+ * contact linked to ANOTHER record of the same entity: `reject` fails the
+ * write (409 `record_duplicate`); `flag` (default) accepts it and raises a
+ * record duplicate pair for review.
+ */
+export type ContactBindingDuplicatePolicy = 'reject' | 'flag'
+
+/**
+ * The entity-level contact-binding setting — meaningful only for entities
+ * with `contact-address` attributes; absent on the wire means `flag`. Mirror
+ * of the Go `metamodel.ContactBinding`.
+ */
+export interface EntityContactBinding {
+  duplicate_policy: ContactBindingDuplicatePolicy
+}
+
+export const EntityContactBindingSchema = z.object({
+  duplicate_policy: z.enum(['reject', 'flag']),
+})
+
 export interface Entity extends AuditFields {
   slug: string
   name: string
@@ -584,6 +659,11 @@ export interface Entity extends AuditFields {
    * (default).
    */
   public_record_access: PublicAccessOperation[]
+  /**
+   * Contact-binding setting (see `EntityContactBinding`). Optional: a Go
+   * build that predates the setting omits it, which means `flag`.
+   */
+  contact_binding?: EntityContactBinding
   module_slug: string
   /**
    * Liquid template that renders a human-readable title for an instance
@@ -606,6 +686,7 @@ export const EntitySchema = AuditFieldsSchema.extend({
   // Default keeps older API responses (pre-`public_record_access` rollout)
   // parsing cleanly.
   public_record_access: z.array(PublicAccessOperationSchema).default([]),
+  contact_binding: EntityContactBindingSchema.optional(),
   module_slug: z.string(),
   // Default keeps older API responses (pre-`title_template` rollout) parsing
   // cleanly — the field is non-optional in the TS surface but tolerant on
@@ -648,6 +729,10 @@ export interface CreateEntityRequest {
    * the field resets it to private.
    */
   public_record_access?: PublicAccessOperation[]
+  /**
+   * Contact-binding setting; full-replacement on upsert (omitted = `flag`).
+   */
+  contact_binding?: EntityContactBinding
   module_slug: string
   description: string
   title_template?: string
@@ -661,6 +746,7 @@ export interface UpdateEntityRequest {
   name?: string
   is_remote?: boolean
   public_record_access?: PublicAccessOperation[]
+  contact_binding?: EntityContactBinding
   module_slug?: string
   description?: string
   title_template?: string
@@ -882,6 +968,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 +1040,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 +1053,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 +1097,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 +1346,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 +1354,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 +1383,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 +1431,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
 // ============================================================================