@proteos/sdk 0.18.1

package/src/meta/index.ts

@@ -0,0 +1,227 @@
+import type { ProteosClient } from '../client.js'
+import { type AppService, AppServiceImpl } from './apps.js'
+import { type ComponentService, ComponentServiceImpl } from './components.js'
+import { type EntityService, EntityServiceImpl } from './entities.js'
+import { type ListViewService, ListViewServiceImpl } from './list-views.js'
+import { type ListService, ListServiceImpl } from './lists.js'
+import {
+  type MenuConfigurationService,
+  MenuConfigurationServiceImpl,
+} from './menu-configurations.js'
+import { type ModuleService, ModuleServiceImpl } from './modules.js'
+import { type PageService, PageServiceImpl } from './pages.js'
+import { type VariableService, VariableServiceImpl } from './variables.js'
+
+/**
+ * Client for the Proteos Metadata Service API.
+ * Provides access to all metadata management services.
+ *
+ * @example
+ * ```ts
+ * import { ProteosClient, MetaClient } from 'proteos-sdk';
+ *
+ * const client = new ProteosClient({
+ *   baseUrl: 'https://api.proteos.ai',
+ *   token: 'your-api-token',
+ * });
+ *
+ * const meta = new MetaClient(client);
+ *
+ * // Use services
+ * const entities = await meta.entities.list().all();
+ * const module = await meta.modules.get('my-module');
+ * ```
+ */
+export class MetaClient {
+  /**
+   * Service for managing entity definitions.
+   */
+  readonly entities: EntityService
+
+  /**
+   * Service for managing WebAssembly modules.
+   */
+  readonly modules: ModuleService
+
+  /**
+   * Service for managing configuration and secret variables.
+   */
+  readonly variables: VariableService
+
+  /**
+   * Service for managing UI component definitions.
+   */
+  readonly components: ComponentService
+
+  /**
+   * Service for managing list configurations.
+   */
+  readonly lists: ListService
+
+  /**
+   * Service for managing list view configurations.
+   */
+  readonly listViews: ListViewService
+
+  /**
+   * Service for managing page configurations.
+   */
+  readonly pages: PageService
+
+  /**
+   * Service for managing menu configurations.
+   */
+  readonly menuConfigurations: MenuConfigurationService
+
+  /**
+   * Service for managing apps.
+   */
+  readonly apps: AppService
+
+  /**
+   * Creates a new MetaClient instance.
+   *
+   * @param client - The base ProteosClient to use for API requests
+   */
+  constructor(client: ProteosClient) {
+    this.entities = new EntityServiceImpl(client)
+    this.modules = new ModuleServiceImpl(client)
+    this.variables = new VariableServiceImpl(client)
+    this.components = new ComponentServiceImpl(client)
+    this.lists = new ListServiceImpl(client)
+    this.listViews = new ListViewServiceImpl(client)
+    this.pages = new PageServiceImpl(client)
+    this.menuConfigurations = new MenuConfigurationServiceImpl(client)
+    this.apps = new AppServiceImpl(client)
+  }
+}
+
+export type { AppService } from './apps.js'
+export type { ComponentService } from './components.js'
+export * from './currency/index.js'
+// Re-export service interfaces
+export type { EntityService } from './entities.js'
+// Re-export the layout module (PageLayout types + Zod schemas + control registry)
+export * from './layout/index.js'
+export type { ListViewService } from './list-views.js'
+export type { ListService } from './lists.js'
+export type { MenuConfigurationService } from './menu-configurations.js'
+export type { ModuleService } from './modules.js'
+export type { PageService } from './pages.js'
+// Re-export types
+export type {
+  // App types
+  App,
+  ArrayAttributeMeta,
+  Attribute,
+  AttributeMeta,
+  AttributeType,
+  Column,
+  ComparisonOperator,
+  // Component types
+  Component,
+  CreateAppRequest,
+  CreateComponentRequest,
+  CreateEntityRequest,
+  CreateListRequest,
+  CreateListViewRequest,
+  CreateMenuConfigurationRequest,
+  CreatePageRequest,
+  CreateVariableRequest,
+  // Currency attribute meta + value
+  CurrencyAttributeMeta,
+  CurrencyValue,
+  DatetimeAttributeMeta,
+  DatetimeFormat,
+  DeployModuleRequest,
+  // Entity types
+  Entity,
+  EntityWithSchema,
+  EnumAttributeMeta,
+  EnumValue,
+  // File attribute meta
+  FileAttributeMeta,
+  FilterElement,
+  FilterGroup,
+  // List types
+  List,
+  ListAppsOptions,
+  ListComponentsOptions,
+  ListEntitiesOptions,
+  ListListsOptions,
+  ListListViewsOptions,
+  ListMenuConfigurationsOptions,
+  ListModulesOptions,
+  ListPagesOptions,
+  ListVariablesOptions,
+  // ListView types
+  ListView,
+  LogicalOperator,
+  // MenuConfiguration types
+  MenuConfiguration,
+  MenuItem,
+  // Shared types
+  MetaListOptions,
+  // Module types
+  Module,
+  ModuleStatus,
+  NumberAttributeMeta,
+  ObjectAttributeMeta,
+  OnDeleteAction,
+  // Page types
+  Page,
+  PageAction,
+  // Relation attribute meta
+  RelationAttributeMeta,
+  SortConfig,
+  SortDirection,
+  StringAttributeMeta,
+  StringFormat,
+  UpdateAppRequest,
+  UpdateComponentRequest,
+  UpdateEntityRequest,
+  UpdateListRequest,
+  UpdateListViewRequest,
+  UpdateMenuConfigurationRequest,
+  UpdatePageRequest,
+  UpdateVariableRequest,
+  // User attribute meta
+  UserAttributeMeta,
+  // Variable types
+  Variable,
+} from './types.js'
+// Re-export value-level constants
+// Re-export Zod schemas
+export {
+  AppSchema,
+  AttributeSchema,
+  ColumnSchema,
+  ComponentSchema,
+  CurrencyAttributeMetaSchema,
+  EntitySchema,
+  EntityWithSchemaSchema,
+  FileAttributeMetaSchema,
+  FilterElementSchema,
+  FilterGroupSchema,
+  isPlatformAttributeName,
+  ListSchema,
+  ListViewSchema,
+  MenuConfigurationSchema,
+  MenuItemSchema,
+  MenuItemType,
+  ModuleSchema,
+  OnDeleteActionSchema,
+  PageActionSchema,
+  PageSchema,
+  PLATFORM_ATTRIBUTE_NAMES,
+  parseCurrencyMeta,
+  parseFileMeta,
+  parseRelationMeta,
+  parseUserMeta,
+  platformAttributes,
+  RelationAttributeMetaSchema,
+  SortConfigSchema,
+  UserAttributeMetaSchema,
+  VariableSchema,
+} from './types.js'
+export type { VariableService } from './variables.js'

package/src/meta/layout/common-props.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod'
+import { type FilterGroup, FilterGroupSchema } from '../filters.js'
+import { type SizeValue, SizeValueSchema } from './size-value.js'
+
+/**
+ * Cross-axis alignment values. On Row / Column the same string also drives
+ * arrangement of children (cross-axis); on a leaf element it acts as
+ * align-self.
+ */
+export type LayoutAlign = 'start' | 'center' | 'end' | 'stretch'
+
+export type LayoutJustify = 'start' | 'center' | 'end' | 'between' | 'around'
+
+export type LayoutGap = 'xs' | 'sm' | 'md' | 'lg'
+
+const AlignSchema = z.enum(['start', 'center', 'end', 'stretch'])
+const JustifySchema = z.enum(['start', 'center', 'end', 'between', 'around'])
+const GapSchema = z.enum(['xs', 'sm', 'md', 'lg'])
+
+/**
+ * Partial sizing knobs reused by ResponsiveSizing.
+ */
+export interface SizingProps {
+  width?: SizeValue
+  height?: SizeValue
+  grow?: number
+  shrink?: number
+  align?: LayoutAlign
+}
+
+const SizingPropsSchema = z.object({
+  width: SizeValueSchema.optional(),
+  height: SizeValueSchema.optional(),
+  grow: z.number().optional(),
+  shrink: z.number().optional(),
+  align: AlignSchema.optional(),
+})
+
+export interface ResponsiveSizing {
+  sm?: SizingProps
+  md?: SizingProps
+  lg?: SizingProps
+}
+
+const ResponsiveSizingSchema = z.object({
+  sm: SizingPropsSchema.optional(),
+  md: SizingPropsSchema.optional(),
+  lg: SizingPropsSchema.optional(),
+})
+
+/**
+ * Common properties present on every LayoutElement.
+ *
+ * `visible_when` and `read_only_when` reuse the `FilterGroup` predicate model
+ * already used by lists and the data-service URL query convention — same
+ * operators, same and/or composition, same `value: string` (pipe-joined for
+ * `in` / `not_in`).
+ *
+ * `align` here is align-self (override of the parent's cross-axis arrangement
+ * for this child). On Row / Column it is shadowed by an outer `align` whose
+ * semantic is the cross-axis arrangement applied to children.
+ */
+export interface CommonProps {
+  id?: string
+  visible_when?: FilterGroup
+  read_only_when?: FilterGroup
+  width?: SizeValue
+  height?: SizeValue
+  grow?: number
+  shrink?: number
+  align?: LayoutAlign
+  responsive?: ResponsiveSizing
+}
+
+/**
+ * The Zod shape for CommonProps. Exported so individual element schemas can
+ * spread it via `.extend(commonPropsShape)`.
+ */
+export const commonPropsShape = {
+  id: z.string().optional(),
+  visible_when: FilterGroupSchema.optional(),
+  read_only_when: FilterGroupSchema.optional(),
+  width: SizeValueSchema.optional(),
+  height: SizeValueSchema.optional(),
+  grow: z.number().optional(),
+  shrink: z.number().optional(),
+  align: AlignSchema.optional(),
+  responsive: ResponsiveSizingSchema.optional(),
+} as const
+
+export const layoutAlignShape = AlignSchema
+export const layoutJustifyShape = JustifySchema
+export const layoutGapShape = GapSchema

package/src/meta/layout/control-registry.json

@@ -0,0 +1,70 @@
+{
+  "_comment": "SOURCE OF TRUTH for the page-layout control registry. Each entry under `controls` declares the primary control slug and the full compatible list for one (type[+format|+items.type]) combination. Renderer dispatches off `primary`; inspector picker dispatches off `compatible`. Edit this file then run `go run ./scripts/codegen/page-layout-registry` from the repo root to regenerate packages/go/model/page_layout_registry_gen.go.",
+  "_attributeTypes": "Top-level keys MUST match the Go canonical AttributeType union in packages/go/model/meta/attribute.go (string · number · integer · boolean · array · object · datetime · enum · relation · user · currency · knowledge-text · file). `byFormat` keys for `string` MUST match StringFormat (email · uri · uuid · hostname · ipv4 · ipv6). `byFormat` keys for `datetime` MUST match DatetimeFormat (date-time · date · time · duration). `byItemsType` for `array` keys on the item Attribute's type. A null `primary` with empty `compatible` means \"render-only fallback\" — see plan §3.2.5.",
+  "_slugRoster": "v1 ships only lib-backed slugs. Slugs without a backing @proteos/ui component (markdown · json-editor · slider · stepper · percent · user-card) are intentionally omitted; they return when the matching lib primitive ships. See plan §3.2.4 / §7.3. The `user-picker` slug is backed by the web client's UserCombobox (account/user-service people picker). The `currency` slug is backed by the web client's currency control (CurrencyInput: decimal amount + ISO-4217 picker).",
+  "builtInControls": [
+    "text",
+    "textarea",
+    "email",
+    "url",
+    "password",
+    "number",
+    "switch",
+    "checkbox",
+    "select",
+    "radio-group",
+    "chip-group",
+    "multi-select",
+    "date-picker",
+    "datetime-picker",
+    "time-picker",
+    "tag-input",
+    "entity-picker",
+    "user-picker",
+    "currency",
+    "knowledge-text",
+    "file"
+  ],
+  "controls": {
+    "string": {
+      "primary": "text",
+      "compatible": ["text", "textarea", "password"],
+      "byFormat": {
+        "email": { "primary": "email", "compatible": ["email", "text"] },
+        "uri": { "primary": "url", "compatible": ["url", "text"] },
+        "uuid": { "primary": "text", "compatible": ["text"] },
+        "hostname": { "primary": "text", "compatible": ["text"] },
+        "ipv4": { "primary": "text", "compatible": ["text"] },
+        "ipv6": { "primary": "text", "compatible": ["text"] }
+      }
+    },
+    "number": { "primary": "number", "compatible": ["number"] },
+    "integer": { "primary": "number", "compatible": ["number"] },
+    "boolean": { "primary": "switch", "compatible": ["switch", "checkbox"] },
+    "enum": { "primary": "select", "compatible": ["select", "radio-group", "chip-group"] },
+    "array": {
+      "primary": "tag-input",
+      "compatible": ["tag-input"],
+      "byItemsType": {
+        "string": { "primary": "tag-input", "compatible": ["tag-input"] },
+        "enum": { "primary": "multi-select", "compatible": ["multi-select"] }
+      }
+    },
+    "datetime": {
+      "primary": null,
+      "compatible": [],
+      "byFormat": {
+        "date": { "primary": "date-picker", "compatible": ["date-picker"] },
+        "date-time": { "primary": "datetime-picker", "compatible": ["datetime-picker"] },
+        "time": { "primary": "time-picker", "compatible": ["time-picker"] },
+        "duration": { "primary": null, "compatible": [] }
+      }
+    },
+    "object": { "primary": null, "compatible": [] },
+    "relation": { "primary": "entity-picker", "compatible": ["entity-picker"] },
+    "user": { "primary": "user-picker", "compatible": ["user-picker"] },
+    "currency": { "primary": "currency", "compatible": ["currency"] },
+    "knowledge-text": { "primary": "knowledge-text", "compatible": ["knowledge-text"] },
+    "file": { "primary": "file", "compatible": ["file"] }
+  }
+}

package/src/meta/layout/control-registry.ts

@@ -0,0 +1,92 @@
+import registry from './control-registry.json' with { type: 'json' }
+
+/* =========================================================================
+   Field control registry — source of truth: ./control-registry.json
+   (which is also the input to scripts/codegen/page-layout-registry, so
+   the Go validator and the TS renderer agree on every slug).
+
+   Two surfaces:
+
+   - `BUILT_IN_CONTROLS`        : the slug allow-list shipped by
+                                  @proteos/ui's PageLayoutRenderer.
+   - `lookupControls(attr)`     : per-(type+format|items.type) bucket.
+     `lookupPrimaryControl`     : the bucket's primary (renderer dispatch).
+     `lookupCompatibleControls` : the bucket's compatible list (inspector
+                                  picker).
+
+   Resolution walks the discriminator chain: type → byFormat[meta.format]
+   for `string` and `datetime`, type → byItemsType[meta.items.type] for
+   `array`. Falls back to the type-level entry when no narrower bucket
+   matches. A null primary with empty compatible signals "render-only
+   fallback" (see plan §3.2.5).
+   ========================================================================= */
+
+export const BUILT_IN_CONTROLS = registry.builtInControls as readonly string[]
+export type BuiltInControlSlug = (typeof BUILT_IN_CONTROLS)[number]
+
+export interface ControlBucket {
+  readonly primary: string | null
+  readonly compatible: readonly string[]
+}
+
+interface ControlBucketJson extends ControlBucket {
+  readonly byFormat?: Readonly<Record<string, ControlBucketJson>>
+  readonly byItemsType?: Readonly<Record<string, ControlBucketJson>>
+}
+
+const CONTROLS = registry.controls as Readonly<Record<string, ControlBucketJson>>
+
+/** True when `slug` matches a built-in control. */
+export function isBuiltInControl(slug: string): boolean {
+  return (BUILT_IN_CONTROLS as readonly string[]).includes(slug)
+}
+
+/**
+ * Minimal Attribute shape the lookup helpers need. The SDK's full
+ * `Attribute` type extends this; consumers can pass either.
+ */
+export interface AttributeForLookup {
+  type: string
+  meta?: {
+    format?: string
+    items?: { type?: string }
+  } | null
+}
+
+/**
+ * Resolves the full ControlBucket for an attribute. Walks
+ * type → byFormat[meta.format] (string/datetime) or
+ * type → byItemsType[meta.items.type] (array), falling back to the
+ * type-level entry.
+ *
+ * Returns `{ primary: null, compatible: [] }` when neither the type
+ * nor any narrower bucket matches — including when the attribute type
+ * is unknown to the registry (e.g. legacy wire data).
+ */
+export function lookupControls(attr: AttributeForLookup): ControlBucket {
+  const typeBucket = CONTROLS[attr.type]
+  if (!typeBucket) return EMPTY
+
+  const meta = attr.meta ?? undefined
+  const format = meta?.format
+  if (format && typeBucket.byFormat?.[format]) {
+    return typeBucket.byFormat[format]
+  }
+  const itemsType = meta?.items?.type
+  if (itemsType && typeBucket.byItemsType?.[itemsType]) {
+    return typeBucket.byItemsType[itemsType]
+  }
+  return typeBucket
+}
+
+/** Convenience: the primary slug, or null for the read-only fallback. */
+export function lookupPrimaryControl(attr: AttributeForLookup): string | null {
+  return lookupControls(attr).primary
+}
+
+/** Convenience: the compatible slug list (empty for the read-only fallback). */
+export function lookupCompatibleControls(attr: AttributeForLookup): readonly string[] {
+  return lookupControls(attr).compatible
+}
+
+const EMPTY: ControlBucket = { primary: null, compatible: [] }

package/src/meta/layout/elements.ts

@@ -0,0 +1,203 @@
+import { z } from 'zod'
+import { type FilterGroup, FilterGroupSchema } from '../filters.js'
+import {
+  type CommonProps,
+  commonPropsShape,
+  layoutAlignShape,
+  layoutGapShape,
+  layoutJustifyShape,
+} from './common-props.js'
+
+export const LayoutElementType = {
+  Row: 'row',
+  Column: 'column',
+  Section: 'section',
+  Tabs: 'tabs',
+  Field: 'field',
+  RelatedList: 'related_list',
+  Component: 'component',
+  Divider: 'divider',
+  Text: 'text',
+} as const
+export type LayoutElementType = (typeof LayoutElementType)[keyof typeof LayoutElementType]
+
+export type RowElement = CommonProps & {
+  type: 'row'
+  gap?: 'xs' | 'sm' | 'md' | 'lg'
+  /** When true (default), children flow to the next line if they don't fit. */
+  allows_wrap?: boolean
+  align?: 'start' | 'center' | 'end' | 'stretch'
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around'
+  children: LayoutElement[]
+}
+
+export type ColumnElement = CommonProps & {
+  type: 'column'
+  gap?: 'xs' | 'sm' | 'md' | 'lg'
+  align?: 'start' | 'center' | 'end' | 'stretch'
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around'
+  children: LayoutElement[]
+}
+
+export type SectionElement = CommonProps & {
+  type: 'section'
+  title?: string
+  description?: string
+  is_collapsible?: boolean
+  default_collapsed?: boolean
+  content: LayoutElement
+}
+
+export type LayoutTab = {
+  id: string
+  label: string
+  icon?: string
+  visible_when?: FilterGroup
+  content: LayoutElement
+}
+
+export type TabsElement = CommonProps & {
+  type: 'tabs'
+  tabs: LayoutTab[]
+  default_tab_id?: string
+}
+
+export type FieldElement = CommonProps & {
+  type: 'field'
+  attribute: string
+  label?: string | null
+  description?: string
+  placeholder?: string
+  is_read_only?: boolean
+  is_required?: boolean
+  empty_display?: 'dash' | 'hide' | string
+  control?: string
+  control_props?: Record<string, unknown>
+}
+
+/**
+ * Lists records of `related_entity_slug` that reference the current record
+ * through the `via_attribute` relation attribute. Replaces the pre-LUM-20
+ * `relationshipId` reference — the relation is identified directly by the
+ * attribute on the host entity. `list_slug` optionally pins which list
+ * definition drives the column / sort / filter model; when omitted, the
+ * renderer falls back to the first list configured for the related entity.
+ */
+export type RelatedListElement = CommonProps & {
+  type: 'related_list'
+  related_entity_slug: string
+  via_attribute: string
+  list_slug?: string
+}
+
+export type ComponentElement = CommonProps & {
+  type: 'component'
+  component_slug: string
+  props?: Record<string, unknown>
+}
+
+export type DividerElement = CommonProps & {
+  type: 'divider'
+}
+
+export type TextVariant = 'heading' | 'subheading' | 'body' | 'caption' | 'callout'
+
+export type TextElement = CommonProps & {
+  type: 'text'
+  variant: TextVariant
+  content: string
+}
+
+export type LayoutElement =
+  | RowElement
+  | ColumnElement
+  | SectionElement
+  | TabsElement
+  | FieldElement
+  | RelatedListElement
+  | ComponentElement
+  | DividerElement
+  | TextElement
+
+// ──────────────────────────────────────────────────────────── Schemas ──
+
+export const LayoutElementSchema: z.ZodType<LayoutElement> = z.lazy(() =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('row'),
+      ...commonPropsShape,
+      gap: layoutGapShape.optional(),
+      allows_wrap: z.boolean().optional(),
+      align: layoutAlignShape.optional(),
+      justify: layoutJustifyShape.optional(),
+      children: z.array(LayoutElementSchema),
+    }),
+    z.object({
+      type: z.literal('column'),
+      ...commonPropsShape,
+      gap: layoutGapShape.optional(),
+      align: layoutAlignShape.optional(),
+      justify: layoutJustifyShape.optional(),
+      children: z.array(LayoutElementSchema),
+    }),
+    z.object({
+      type: z.literal('section'),
+      ...commonPropsShape,
+      title: z.string().optional(),
+      description: z.string().optional(),
+      is_collapsible: z.boolean().optional(),
+      default_collapsed: z.boolean().optional(),
+      content: LayoutElementSchema,
+    }),
+    z.object({
+      type: z.literal('tabs'),
+      ...commonPropsShape,
+      tabs: z.array(
+        z.object({
+          id: z.string().min(1),
+          label: z.string().min(1),
+          icon: z.string().optional(),
+          visible_when: FilterGroupSchema.optional(),
+          content: LayoutElementSchema,
+        }),
+      ),
+      default_tab_id: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('field'),
+      ...commonPropsShape,
+      attribute: z.string().min(1),
+      label: z.string().nullable().optional(),
+      description: z.string().optional(),
+      placeholder: z.string().optional(),
+      is_read_only: z.boolean().optional(),
+      is_required: z.boolean().optional(),
+      empty_display: z.string().optional(),
+      control: z.string().optional(),
+      control_props: z.record(z.unknown()).optional(),
+    }),
+    z.object({
+      type: z.literal('related_list'),
+      ...commonPropsShape,
+      related_entity_slug: z.string().min(1),
+      via_attribute: z.string().min(1),
+      list_slug: z.string().min(1).optional(),
+    }),
+    z.object({
+      type: z.literal('component'),
+      ...commonPropsShape,
+      component_slug: z.string().min(1),
+      props: z.record(z.unknown()).optional(),
+    }),
+    z.object({
+      type: z.literal('divider'),
+      ...commonPropsShape,
+    }),
+    z.object({
+      type: z.literal('text'),
+      ...commonPropsShape,
+      variant: z.enum(['heading', 'subheading', 'body', 'caption', 'callout']),
+      content: z.string().min(1),
+    }),
+  ]),
+) as unknown as z.ZodType<LayoutElement>