@proteos/sdk 0.18.1

package/src/meta/types.ts

@@ -0,0 +1,1115 @@
+import { z } from 'zod'
+import type { AuditFields, ListOptions } from '../types/common.js'
+import { AuditFieldsSchema } from '../types/common.js'
+import { type PageLayout, PageLayoutSchema } from './layout/page-layout.js'
+
+export type { PageLayout } from './layout/page-layout.js'
+
+// ============================================================================
+// Shared Types
+// ============================================================================
+
+/**
+ * Base list options with source filters for the meta namespace.
+ */
+export interface MetaListOptions extends ListOptions {
+  created_by?: string
+  updated_by?: string
+}
+
+// ============================================================================
+// Entity Types
+// ============================================================================
+
+/**
+ * Attribute type — canonical to the Go `model.AttributeType` union
+ * (packages/go/model/meta/attribute.go). The members below are the
+ * full set; format/structural variation lives on `Attribute.meta` (see
+ * `AttributeMeta` below), not on the type discriminator.
+ */
+export type AttributeType =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'array'
+  | 'object'
+  | 'datetime'
+  | 'enum'
+  | 'relation'
+  | 'user'
+  | 'currency'
+  | 'knowledge-text'
+  | 'file'
+
+// ── Attribute meta (sub-discriminators) ──────────────────────────────
+// Mirrors the Go `*AttributeMeta` types in
+// packages/go/model/attribute-{string,number,datetime,array,object,enum}.go.
+
+/** JSON-Schema string formats carried by `string` attributes. */
+export type StringFormat = 'email' | 'uri' | 'uuid' | 'hostname' | 'ipv4' | 'ipv6'
+
+export interface StringAttributeMeta {
+  format?: StringFormat
+  min_length?: number
+  max_length?: number
+  pattern?: string
+}
+
+export interface NumberAttributeMeta {
+  minimum?: number
+  maximum?: number
+  exclusive_minimum?: number
+  exclusive_maximum?: number
+  multiple_of?: number
+}
+
+/** Datetime storage/display behavior. `format` is required. */
+export type DatetimeFormat = 'date-time' | 'date' | 'time' | 'duration'
+
+export interface DatetimeAttributeMeta {
+  format: DatetimeFormat
+  minimum?: string
+  maximum?: string
+}
+
+export interface ArrayAttributeMeta {
+  items?: Attribute
+  min_items?: number
+  max_items?: number
+  items_must_be_unique?: boolean
+}
+
+export interface ObjectAttributeMeta {
+  attributes?: Attribute[]
+}
+
+export interface EnumValue {
+  value: string
+  label?: string
+  description?: string
+}
+
+export interface EnumAttributeMeta {
+  values: EnumValue[]
+}
+
+/**
+ * Policy applied to the host row when the related row is deleted. Mirror
+ * of `model.OnDeleteAction`. The runtime semantic is enforced at the
+ * data-service level; this metadata declares the intent.
+ */
+export type OnDeleteAction = 'cascade' | 'restrict' | 'set-null'
+
+export const OnDeleteActionSchema = z.enum(['cascade', 'restrict', 'set-null'])
+
+/**
+ * Metadata for a `relation`-typed attribute. The attribute is a foreign-key
+ * column on the host entity pointing at `related_attribute` on
+ * `related_entity_slug`. `predicate` reads from the host outward (e.g. on
+ * `Order.customerId` with `predicate: "is placed by"`, the sentence is
+ * "Order is placed by Customer").
+ */
+export interface RelationAttributeMeta {
+  related_entity_slug: string
+  related_attribute: string
+  predicate: string
+  description?: string
+  on_delete: OnDeleteAction
+}
+
+export const RelationAttributeMetaSchema = z.object({
+  related_entity_slug: z.string(),
+  related_attribute: z.string(),
+  predicate: z.string(),
+  description: z.string().optional(),
+  on_delete: OnDeleteActionSchema,
+})
+
+/**
+ * Metadata for a `user`-typed attribute. A user attribute stores a
+ * {@link UserRef} `{ type, id }` (the account-service identity plus its
+ * kind), rendered as a people picker that resolves and filters on `id`. Mirror
+ * of the Go `metamodel.UserAttributeMeta`.
+ *
+ * It carries no required configuration today; the shape exists for parity
+ * with the other metas and reserves room for future options (e.g.
+ * multi-user selection).
+ */
+export interface UserAttributeMeta {
+  description?: string
+}
+
+export const UserAttributeMetaSchema = z.object({
+  description: z.string().optional(),
+})
+
+/**
+ * The stored value of a `currency`-typed attribute: an exact decimal `amount`
+ * (a STRING, never a JS number — preserves financial-system precision and
+ * trailing zeros) paired with an ISO-4217 `currency_code`. This is the wire
+ * shape; the `@proteos/ui` `CurrencyInput` and the web control both read/write
+ * it directly to avoid an adapter.
+ */
+export interface CurrencyValue {
+  amount: string
+  currency_code: string
+}
+
+/**
+ * Metadata for a `currency`-typed attribute. Both fields are optional: when
+ * `allowed_currency_codes` is empty/absent, any ISO-4217 code is accepted;
+ * `default_currency_code` seeds the picker for new values and must be a member
+ * of `allowed_currency_codes` when that allow-list is set. Mirror of the Go
+ * `metamodel.CurrencyAttributeMeta`.
+ */
+export interface CurrencyAttributeMeta {
+  default_currency_code?: string
+  allowed_currency_codes?: string[]
+}
+
+export const CurrencyAttributeMetaSchema = z.object({
+  default_currency_code: z.string().optional(),
+  allowed_currency_codes: z.array(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
+ * persists only `{ id }`; `content` is transient — accepted on writes (the
+ * text to materialize into the node) and filled on single-record reads.
+ * Clients may also write a bare string as shorthand for `{ content }`.
+ * Mirror of the Go `common.KnowledgeNodeRef`.
+ */
+export interface KnowledgeNodeRef {
+  id: string
+  content?: string
+}
+
+/**
+ * Metadata for a `knowledge-text`-typed attribute. The value is a
+ * {@link KnowledgeNodeRef}; the data-service materializes client-sent text
+ * into a knowledge node before persisting. Mirror of the Go
+ * `metamodel.KnowledgeTextAttributeMeta`.
+ *
+ * It carries no required configuration today; the shape exists for parity
+ * with the other metas and reserves room for future options (e.g. node
+ * labels, status overrides).
+ */
+export interface KnowledgeTextAttributeMeta {
+  description?: string
+}
+
+export const KnowledgeTextAttributeMetaSchema = z.object({
+  description: z.string().optional(),
+})
+
+/**
+ * Metadata for a `file`-typed attribute. The value is a {@link FileRef}
+ * `{ id, name }` referencing a storage-service file; the frontend uploads to
+ * the storage-service and writes the resulting id + name. Mirror of the Go
+ * `metamodel.FileAttributeMeta`.
+ *
+ * It carries no required configuration today; the shape exists for parity with
+ * the other metas and reserves room for future options (e.g. accepted content
+ * types, max size).
+ */
+export interface FileAttributeMeta {
+  description?: string
+}
+
+export const FileAttributeMetaSchema = z.object({
+  description: z.string().optional(),
+})
+
+/**
+ * Discriminated union of attribute metas. The wire JSON carries the
+ * appropriate shape based on `Attribute.type`; runtime consumers can
+ * narrow via the `type` field.
+ */
+export type AttributeMeta =
+  | StringAttributeMeta
+  | NumberAttributeMeta
+  | DatetimeAttributeMeta
+  | ArrayAttributeMeta
+  | ObjectAttributeMeta
+  | EnumAttributeMeta
+  | RelationAttributeMeta
+  | UserAttributeMeta
+  | CurrencyAttributeMeta
+  | KnowledgeTextAttributeMeta
+  | FileAttributeMeta
+
+/**
+ * Entity attribute definition. Mirrors `model.Attribute` in the Go SDK.
+ */
+export interface Attribute {
+  name: string
+  type: AttributeType
+  label: string
+  description?: string
+  is_required: boolean
+  is_nullable?: boolean
+  is_unique: boolean
+  is_read_only?: boolean
+  /**
+   * Platform-managed flag. Marks the canonical platform attributes (id,
+   * created_at, updated_at, created_by, updated_by) — auto-added to every
+   * entity, locked in the designer, and rejected from client redefinition.
+   * Mirrors `IsPlatformManaged` in the Go `metamodel.Attribute`.
+   */
+  is_platform_managed?: boolean
+  default_value?: unknown
+  /**
+   * Type-specific metadata. The concrete shape is determined by `type`
+   * — e.g. `type: 'string'` carries `StringAttributeMeta`. The wire
+   * field name is `meta`; `options` is an older alias still emitted by
+   * some service paths and accepted for backwards compatibility.
+   */
+  meta?: AttributeMeta
+  /** @deprecated Older wire alias for `meta`. Prefer `meta`. */
+  options?: Record<string, unknown>
+}
+
+/**
+ * Canonical platform attribute names — the system-managed set every entity
+ * carries. Mirrors `metamodel.PlatformAttribute*` constants in the Go model.
+ */
+export const PLATFORM_ATTRIBUTE_NAMES = [
+  'id',
+  'created_at',
+  'updated_at',
+  'created_by',
+  'updated_by',
+] as const
+
+/** True when `name` is one of the canonical platform attributes. */
+export function isPlatformAttributeName(name: string): boolean {
+  return (PLATFORM_ATTRIBUTE_NAMES as readonly string[]).includes(name)
+}
+
+/**
+ * The canonical platform attributes, in display order. Mirror of the Go
+ * `metamodel.PlatformAttributes()`. Used by the entity designer to seed new
+ * entities; the backend re-asserts these on save regardless.
+ */
+export function platformAttributes(): Attribute[] {
+  return [
+    {
+      name: 'id',
+      type: 'string',
+      label: 'Id',
+      description: 'Unique identifier of the record.',
+      is_required: false,
+      is_unique: true,
+      is_read_only: true,
+      is_platform_managed: true,
+    },
+    {
+      name: 'created_at',
+      type: 'datetime',
+      label: 'Created At',
+      description: 'Timestamp when the record was created.',
+      is_required: false,
+      is_unique: false,
+      is_read_only: true,
+      is_platform_managed: true,
+      meta: { format: 'date-time' },
+    },
+    {
+      name: 'updated_at',
+      type: 'datetime',
+      label: 'Updated At',
+      description: 'Timestamp when the record was last updated.',
+      is_required: false,
+      is_unique: false,
+      is_read_only: true,
+      is_platform_managed: true,
+      meta: { format: 'date-time' },
+    },
+    {
+      name: 'created_by',
+      type: 'user',
+      label: 'Created By',
+      description: 'User who created the record ("platform" for system writes).',
+      is_required: false,
+      is_unique: false,
+      is_read_only: true,
+      is_platform_managed: true,
+    },
+    {
+      name: 'updated_by',
+      type: 'user',
+      label: 'Updated By',
+      description: 'User who last updated the record ("platform" for system writes).',
+      is_required: false,
+      is_unique: false,
+      is_read_only: true,
+      is_platform_managed: true,
+    },
+  ]
+}
+
+// Schema validation is intentionally lax on `type` (z.string()) and
+// `meta` (z.unknown()) because (a) wire data may carry legacy values
+// from older service deploys, and (b) the renderer narrows on
+// `attribute.type` at the use site. Stricter narrowing happens in
+// renderer-side helpers (e.g. `lookupControls(attr)` from the layout
+// module), not in the schema parse.
+export const AttributeSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  is_required: z.boolean(),
+  is_nullable: z.boolean().optional(),
+  is_unique: z.boolean(),
+  is_read_only: z.boolean().optional(),
+  default_value: z.unknown().optional(),
+  meta: z.unknown().optional(),
+  options: z.record(z.unknown()).optional(),
+})
+
+/**
+ * Returns the typed `RelationAttributeMeta` when `attr` is a relation
+ * attribute with a valid meta shape; null otherwise. The `AttributeSchema`
+ * intentionally keeps `meta` lax, so callers that need the relation fields
+ * narrowed should go through this helper rather than casting.
+ */
+export function parseRelationMeta(attr: Attribute): RelationAttributeMeta | null {
+  if (attr.type !== 'relation') return null
+  const parsed = RelationAttributeMetaSchema.safeParse(attr.meta)
+  return parsed.success ? parsed.data : null
+}
+
+/**
+ * Returns the typed `UserAttributeMeta` when `attr` is a user attribute;
+ * null otherwise. User meta is optional (and usually absent), so a user
+ * attribute with no meta still resolves to an empty `{}` rather than null.
+ */
+export function parseCurrencyMeta(attr: Attribute): CurrencyAttributeMeta | null {
+  if (attr.type !== 'currency') return null
+  const parsed = CurrencyAttributeMetaSchema.safeParse(attr.meta ?? {})
+  return parsed.success ? parsed.data : null
+}
+
+export function parseUserMeta(attr: Attribute): UserAttributeMeta | null {
+  if (attr.type !== 'user') return null
+  if (attr.meta == null) return {}
+  const parsed = UserAttributeMetaSchema.safeParse(attr.meta)
+  return parsed.success ? parsed.data : {}
+}
+
+/**
+ * Returns the typed `KnowledgeTextAttributeMeta` when `attr` is a
+ * knowledge-text attribute; null otherwise. Knowledge-text meta is optional
+ * (and usually absent), so a knowledge-text attribute with no meta still
+ * resolves to an empty `{}` rather than null.
+ */
+export function parseKnowledgeTextMeta(attr: Attribute): KnowledgeTextAttributeMeta | null {
+  if (attr.type !== 'knowledge-text') return null
+  if (attr.meta == null) return {}
+  const parsed = KnowledgeTextAttributeMetaSchema.safeParse(attr.meta)
+  return parsed.success ? parsed.data : {}
+}
+
+/**
+ * Returns the typed `FileAttributeMeta` when `attr` is a file attribute; null
+ * otherwise. File meta is optional (and usually absent), so a file attribute
+ * with no meta still resolves to an empty `{}` rather than null.
+ */
+export function parseFileMeta(attr: Attribute): FileAttributeMeta | null {
+  if (attr.type !== 'file') return null
+  if (attr.meta == null) return {}
+  const parsed = FileAttributeMetaSchema.safeParse(attr.meta)
+  return parsed.success ? parsed.data : {}
+}
+
+/**
+ * Entity definition.
+ * Note: Entity uses `slug` as its primary identifier, not `id`.
+ */
+export interface Entity extends AuditFields {
+  slug: string
+  name: string
+  description: string
+  is_remote: boolean
+  module_slug: string
+  /**
+   * Liquid template that renders a human-readable title for an instance
+   * (record) of this entity — e.g. `{{ first_name }} {{ last_name }}` for a
+   * Customer, `{{ number }}` for an Order. Empty string means "no template
+   * configured"; consumers fall back to the record id.
+   *
+   * Render via `renderRecordTitle(entity, record)` rather than evaluating
+   * the template directly, so the fallback chain stays consistent.
+   */
+  title_template: string
+  attributes: Attribute[]
+}
+
+export const EntitySchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string(),
+  is_remote: z.boolean(),
+  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
+  // the wire.
+  title_template: z.string().default(''),
+  attributes: z.array(AttributeSchema),
+})
+
+/**
+ * Entity with JSON Schema representation.
+ */
+export interface EntityWithSchema extends Entity {
+  schema: Record<string, unknown>
+}
+
+export const EntityWithSchemaSchema = EntitySchema.extend({
+  schema: z.record(z.unknown()),
+})
+
+/**
+ * Options for listing entities.
+ */
+export interface ListEntitiesOptions extends MetaListOptions {
+  slug?: string
+  name?: string
+  is_remote?: boolean
+  module_slug?: string
+}
+
+/**
+ * Request to create an entity.
+ */
+export interface CreateEntityRequest {
+  slug: string
+  name: string
+  is_remote: boolean
+  module_slug: string
+  description: string
+  title_template?: string
+  attributes: Attribute[]
+}
+
+/**
+ * Request to update an entity.
+ */
+export interface UpdateEntityRequest {
+  name?: string
+  is_remote?: boolean
+  module_slug?: string
+  description?: string
+  title_template?: string
+  attributes?: Attribute[]
+}
+
+// ============================================================================
+// Module Types
+// ============================================================================
+
+/**
+ * Module deployment status.
+ */
+export type ModuleStatus =
+  | 'pending'
+  | 'deploying'
+  | 'active'
+  | 'failed'
+  | 'deactivating'
+  | 'inactive'
+
+/**
+ * Module definition.
+ */
+export interface Module extends AuditFields {
+  slug: string
+  org_id: string
+  name: string
+  description: string
+  version: string
+  file_id: string
+  status: ModuleStatus
+  status_details: string
+  is_deactivated: boolean
+}
+
+export const ModuleSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string(),
+  version: z.string(),
+  file_id: z.string(),
+  status: z.enum(['pending', 'deploying', 'active', 'failed', 'deactivating', 'inactive']),
+  status_details: z.string(),
+  is_deactivated: z.boolean(),
+})
+
+/**
+ * Options for listing modules.
+ */
+export interface ListModulesOptions extends MetaListOptions {
+  slug?: string
+  name?: string
+  is_deactivated?: boolean
+  file_id?: string
+  status?: ModuleStatus
+  version?: string
+}
+
+/**
+ * Request to deploy a module.
+ */
+export interface DeployModuleRequest {
+  slug: string
+  version: string
+  name: string
+  description: string
+}
+
+// ============================================================================
+// Variable Types
+// ============================================================================
+
+/**
+ * Configuration/secret variable.
+ */
+export interface Variable extends AuditFields {
+  id: string
+  org_id: string
+  key: string
+  value: string
+  is_secret: boolean
+  module: string
+}
+
+export const VariableSchema = AuditFieldsSchema.extend({
+  id: z.string(),
+  key: z.string(),
+  value: z.string(),
+  is_secret: z.boolean(),
+  module: z.string(),
+})
+
+/**
+ * Options for listing variables.
+ */
+export interface ListVariablesOptions extends MetaListOptions {
+  id?: string
+  key?: string
+  is_secret?: boolean
+  module?: string
+}
+
+/**
+ * Request to create a variable.
+ */
+export interface CreateVariableRequest {
+  key: string
+  value: string
+  is_secret: boolean
+  module: string
+}
+
+/**
+ * Request to update a variable.
+ */
+export interface UpdateVariableRequest {
+  value?: string
+}
+
+// ============================================================================
+// Component Types
+// ============================================================================
+
+/**
+ * UI component definition.
+ * Note: Component uses `slug` as its primary identifier, not `id`.
+ */
+export interface Component extends AuditFields {
+  slug: string
+  org_id: string
+  name: string
+  description: string
+  module_slug: string
+  /** FK to the compiled, single-file ESM bundle in storage. Empty until deployed. Served via {@link ComponentService.bundleUrl}. */
+  bundle_file_id: string
+  /** FK to a tar.gz of the component source directory in storage (provenance / rebuild). Empty until deployed. */
+  source_file_id: string
+  /** The component's JSON Schema, driving the page-designer props editor + runtime validation. `null` until set. */
+  props_schema: Record<string, unknown> | null
+}
+
+export const ComponentSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string(),
+  module_slug: z.string(),
+  bundle_file_id: z.string(),
+  source_file_id: z.string(),
+  props_schema: z.record(z.unknown()).nullable(),
+})
+
+/**
+ * Options for listing components.
+ */
+export interface ListComponentsOptions extends MetaListOptions {
+  slug?: string
+  name?: string
+  module_slug?: string
+}
+
+/**
+ * Request to create a component.
+ */
+export interface CreateComponentRequest {
+  slug: string
+  name: string
+  module_slug: string
+  description: string
+  bundle_file_id?: string
+  source_file_id?: string
+  props_schema?: Record<string, unknown>
+}
+
+/**
+ * Request to update a component.
+ */
+export interface UpdateComponentRequest {
+  name?: string
+  description?: string
+  bundle_file_id?: string
+  source_file_id?: string
+  props_schema?: Record<string, unknown>
+}
+
+// ============================================================================
+// List Types
+// ============================================================================
+
+/**
+ * List column definition.
+ */
+export interface Column {
+  attribute: string
+  label: string
+  width: number
+}
+
+/**
+ * Sort direction.
+ */
+export type SortDirection = 'asc' | 'desc'
+
+/**
+ * Sort configuration.
+ */
+export interface SortConfig {
+  attribute: string
+  direction: SortDirection
+}
+
+// Filter / predicate types live in ./filters.js so the layout module can
+// import FilterGroup without inducing a types.ts ↔ layout cycle.
+import {
+  type ComparisonOperator,
+  type FilterElement,
+  FilterElementSchema,
+  type FilterGroup,
+  FilterGroupSchema,
+  type LogicalOperator,
+} from './filters.js'
+
+export {
+  type ComparisonOperator,
+  type FilterElement,
+  FilterElementSchema,
+  type FilterGroup,
+  FilterGroupSchema,
+  type LogicalOperator,
+}
+
+/**
+ * List configuration.
+ * Note: List uses `slug` as its primary identifier, not `id`.
+ */
+export interface List extends AuditFields {
+  slug: string
+  org_id: string
+  module_slug: string
+  name: string
+  entity_slug: string
+  columns: Column[]
+  sorting: SortConfig[]
+  filters: FilterGroup[]
+}
+
+export const ColumnSchema = z.object({
+  attribute: z.string(),
+  label: z.string(),
+  width: z.number(),
+})
+
+export const SortConfigSchema = z.object({
+  attribute: z.string(),
+  direction: z.enum(['asc', 'desc']),
+})
+
+export const ListSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  module_slug: z.string(),
+  name: z.string(),
+  entity_slug: z.string(),
+  columns: z.array(ColumnSchema),
+  sorting: z.array(SortConfigSchema),
+  filters: z.array(FilterGroupSchema),
+})
+
+/**
+ * Options for listing lists.
+ */
+export interface ListListsOptions extends MetaListOptions {
+  slug?: string
+  name?: string
+  module_slug?: string
+  entity_slug?: string
+}
+
+/**
+ * Request to create a list.
+ */
+export interface CreateListRequest {
+  slug: string
+  module_slug?: string
+  entity_slug: string
+  name: string
+  columns: Column[]
+  sorting: SortConfig[]
+  filters: FilterGroup[]
+}
+
+/**
+ * Request to update a list.
+ */
+export interface UpdateListRequest {
+  name?: string
+  module_slug?: string
+  columns?: Column[]
+  sorting?: SortConfig[]
+  filters?: FilterGroup[]
+}
+
+// ============================================================================
+// ListView Types
+// ============================================================================
+
+/**
+ * List view configuration.
+ * Note: ListView uses `slug` as its primary identifier, not `id`.
+ */
+export interface ListView extends AuditFields {
+  slug: string
+  org_id: string
+  module_slug: string
+  list_slug: string
+  name: string
+  columns: Column[]
+  sorting: SortConfig[]
+  filters: FilterGroup[]
+}
+
+export const ListViewSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  module_slug: z.string(),
+  list_slug: z.string(),
+  name: z.string(),
+  columns: z.array(ColumnSchema),
+  sorting: z.array(SortConfigSchema),
+  filters: z.array(FilterGroupSchema),
+})
+
+/**
+ * Options for listing list views.
+ */
+export interface ListListViewsOptions extends MetaListOptions {
+  slug?: string
+  name?: string
+  module_slug?: string
+  list_slug?: string
+}
+
+/**
+ * Request to create a list view.
+ */
+export interface CreateListViewRequest {
+  slug: string
+  module_slug?: string
+  list_slug: string
+  name: string
+  columns: Column[]
+  sorting?: SortConfig[]
+  filters?: FilterGroup[]
+}
+
+/**
+ * Request to update a list view.
+ */
+export interface UpdateListViewRequest {
+  name?: string
+  module_slug?: string
+  columns?: Column[]
+  sorting?: SortConfig[]
+  filters?: FilterGroup[]
+}
+
+// ============================================================================
+// Page Types
+// ============================================================================
+
+/**
+ * Page action definition. Page-level toolbar item; addressed by permissions
+ * and shortcuts systems.
+ */
+export interface PageAction {
+  label: string
+  icon: string
+  action: string
+}
+
+export const PageActionSchema = z.object({
+  label: z.string(),
+  icon: z.string(),
+  action: z.string(),
+})
+
+/**
+ * Page type. `record` pages render against a single record of `entity_slug`;
+ * `platform` pages are standalone (no record context — e.g. a dashboard
+ * launched from a menu item). `external` is reserved for a future chromeless
+ * variant and is not yet accepted by the API.
+ */
+export type PageType = 'record' | 'platform'
+
+export const PageTypeSchema = z.enum(['record', 'platform'])
+
+/**
+ * Page configuration. A `record` page is the detail-page shape for a single
+ * entity; a `platform` page is standalone (no entity, no record).
+ *
+ * `layout` is a typed tree of LayoutElements (see `./layout`). The legacy
+ * `mainContent` / `side_panel` / `formLayout` shape was replaced in the
+ * v1 PageLayout design.
+ */
+export interface Page extends AuditFields {
+  slug: string
+  name: string
+  module_slug: string
+  type: PageType
+  /** Required for `record` pages; absent on `platform` pages. */
+  entity_slug?: string
+  actions: PageAction[]
+  layout: PageLayout
+}
+
+export const PageSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  name: z.string(),
+  module_slug: z.string(),
+  type: PageTypeSchema,
+  entity_slug: z.string().optional(),
+  actions: z.array(PageActionSchema),
+  layout: PageLayoutSchema,
+})
+
+/**
+ * Options for listing pages.
+ */
+export interface ListPagesOptions extends MetaListOptions {
+  slug?: string
+  name?: string
+  module_slug?: string
+  type?: PageType
+  entity_slug?: string
+}
+
+/**
+ * Request to create a page. `type` defaults to `record` when omitted.
+ * `entity_slug` is required for record pages and must be absent for platform
+ * pages.
+ */
+export interface CreatePageRequest {
+  slug: string
+  name: string
+  module_slug?: string
+  type?: PageType
+  entity_slug?: string
+  actions: PageAction[]
+  layout: PageLayout
+}
+
+/**
+ * Request to update a page. Layout, when present, must be a complete valid
+ * tree — partial / element-level patches are not supported.
+ */
+export interface UpdatePageRequest {
+  name?: string
+  module_slug?: string
+  actions?: PageAction[]
+  layout?: PageLayout
+}
+
+// ============================================================================
+// Menu Configuration Types
+// ============================================================================
+
+/**
+ * Menu item type values. Use as both enum-like constant and type union.
+ */
+export const MenuItemType = {
+  Link: 'link',
+  Group: 'group',
+  Entity: 'entity',
+  Page: 'page',
+  List: 'list',
+} as const
+export type MenuItemType = (typeof MenuItemType)[keyof typeof MenuItemType]
+
+/**
+ * Menu item definition. Matches the backend JSON shape for nested menus.
+ */
+export interface MenuItem {
+  id: string
+  order: number
+  label: string
+  type: MenuItemType
+  icon: string
+  reference?: string
+  children: MenuItem[] | null
+}
+
+/**
+ * Menu configuration.
+ */
+export interface MenuConfiguration extends AuditFields {
+  slug: string
+  name: string
+  module_slug: string
+  app_slug: string
+  items: MenuItem[]
+  is_default: boolean
+}
+
+export const MenuItemSchema = z.lazy(() =>
+  z.object({
+    id: z.string(),
+    order: z.number(),
+    label: z.string(),
+    type: z.enum(['link', 'group', 'entity', 'page', 'list']),
+    icon: z.string(),
+    reference: z.string().optional(),
+    children: z.array(MenuItemSchema).nullable(),
+  }),
+) as unknown as z.ZodType<MenuItem>
+
+export const MenuConfigurationSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  name: z.string(),
+  module_slug: z.string(),
+  app_slug: z.string(),
+  items: z.array(MenuItemSchema),
+  is_default: z.boolean(),
+})
+
+/**
+ * Options for listing menu configurations.
+ */
+export interface ListMenuConfigurationsOptions extends MetaListOptions {
+  slug?: string
+  name?: string
+  module_slug?: string
+  app_slug?: string
+  is_default?: boolean
+}
+
+/**
+ * Request to create a menu configuration.
+ */
+export interface CreateMenuConfigurationRequest {
+  slug: string
+  module_slug?: string
+  name: string
+  app_slug: string
+  items: MenuItem[]
+  is_default: boolean
+}
+
+/**
+ * Request to update a menu configuration.
+ */
+export interface UpdateMenuConfigurationRequest {
+  name?: string
+  module_slug?: string
+  items?: MenuItem[]
+  is_default?: boolean
+}
+
+// ============================================================================
+// App Types
+// ============================================================================
+
+/**
+ * App definition. Apps group menu configurations and other org-scoped
+ * metadata under a stable slug. Slug is unique per org (composite key
+ * `(org_id, slug)`).
+ */
+export interface App extends AuditFields {
+  slug: string
+  org_id: string
+  module_slug: string
+  name: string
+  description: string
+  icon_slug: string
+}
+
+export const AppSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  org_id: z.string(),
+  module_slug: z.string(),
+  name: z.string(),
+  description: z.string(),
+  icon_slug: z.string(),
+})
+
+/**
+ * Options for listing apps.
+ */
+export interface ListAppsOptions extends MetaListOptions {
+  slug?: string
+  name?: string
+  module_slug?: string
+  icon_slug?: string
+}
+
+/**
+ * Request to create an app.
+ */
+export interface CreateAppRequest {
+  slug: string
+  module_slug?: string
+  name: string
+  icon_slug: string
+  description?: string
+}
+
+/**
+ * Request to update an app. Slug and org_id are immutable.
+ */
+export interface UpdateAppRequest {
+  name?: string
+  module_slug?: string
+  description?: string
+  icon_slug?: string
+}