@proteos/sdk 0.18.1

package/src/meta/layout/index.ts

@@ -0,0 +1,41 @@
+export type {
+  CommonProps,
+  LayoutAlign,
+  LayoutGap,
+  LayoutJustify,
+  ResponsiveSizing,
+  SizingProps,
+} from './common-props.js'
+export {
+  type AttributeForLookup,
+  BUILT_IN_CONTROLS,
+  type BuiltInControlSlug,
+  type ControlBucket,
+  isBuiltInControl,
+  lookupCompatibleControls,
+  lookupControls,
+  lookupPrimaryControl,
+} from './control-registry.js'
+export {
+  type ColumnElement,
+  type ComponentElement,
+  type DividerElement,
+  type FieldElement,
+  type LayoutElement,
+  LayoutElementSchema,
+  LayoutElementType,
+  type LayoutTab,
+  type RelatedListElement,
+  type RowElement,
+  type SectionElement,
+  type TabsElement,
+  type TextElement,
+  type TextVariant,
+} from './elements.js'
+export {
+  type PageLayout,
+  PageLayoutSchema,
+  type PageLayoutSidePanel,
+  PageLayoutSidePanelSchema,
+} from './page-layout.js'
+export { type SizeValue, SizeValueSchema } from './size-value.js'

package/src/meta/layout/page-layout.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import { type LayoutElement, LayoutElementSchema } from './elements.js'
+import { type SizeValue, SizeValueSchema } from './size-value.js'
+
+/**
+ * Side panel slot. Rendered as a sticky-by-default right rail; collapses
+ * below the main column on narrow viewports.
+ */
+export interface PageLayoutSidePanel {
+  width?: SizeValue
+  is_sticky?: boolean
+  content: LayoutElement
+}
+
+export const PageLayoutSidePanelSchema = z.object({
+  width: SizeValueSchema.optional(),
+  is_sticky: z.boolean().optional(),
+  content: LayoutElementSchema,
+})
+
+/**
+ * Top-level page layout. Replaces the legacy `mainContent` / `side_panel`
+ * arrays of `PageSection`s with a single typed element tree.
+ */
+export interface PageLayout {
+  version: 1
+  main: LayoutElement
+  side_panel?: PageLayoutSidePanel
+}
+
+export const PageLayoutSchema = z.object({
+  version: z.literal(1),
+  main: LayoutElementSchema,
+  side_panel: PageLayoutSidePanelSchema.optional(),
+})

package/src/meta/layout/size-value.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod'
+
+/**
+ * SizeValue is a polymorphic sizing value used by `width`, `height`, and the
+ * responsive overrides. Accepted forms:
+ *
+ *   - JSON number in [0, 1] for a fraction (0.5 → 50%)
+ *   - "n/m" fraction string ("1/2", "2/3", ...)
+ *   - "Npx" pixel string
+ *   - "N%" percent string
+ *   - "auto"  — size to content
+ *   - "fill"  — grow to fill remaining space
+ */
+export type SizeValue =
+  | number
+  | `${number}/${number}`
+  | `${number}px`
+  | `${number}%`
+  | 'auto'
+  | 'fill'
+
+const SIZE_VALUE_STRING_RE = /^(\d+\/\d+|\d+px|\d+%|auto|fill)$/
+
+export const SizeValueSchema: z.ZodType<SizeValue> = z.union([
+  z.number().min(0).max(1).describe('Fraction in [0, 1]'),
+  z.string().regex(SIZE_VALUE_STRING_RE, 'must match n/m, Npx, N%, "auto", or "fill"'),
+]) as unknown as z.ZodType<SizeValue>

package/src/meta/list-views.ts

@@ -0,0 +1,109 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateListViewRequest,
+  ListListViewsOptions,
+  ListView,
+  UpdateListViewRequest,
+} from './types.js'
+
+const LIST_VIEWS_BASE_PATH = '/meta/v1/list-views'
+
+/**
+ * Service for managing list view configurations.
+ * List views define filtered and sorted views of lists.
+ */
+export interface ListViewService {
+  /**
+   * Lists list views with optional filtering.
+   *
+   * @param options - Filter and pagination options
+   * @returns Async iterator over list views
+   */
+  list(options?: ListListViewsOptions): PageIterator<ListView, ListListViewsOptions>
+
+  /**
+   * Fetches a single page of list views.
+   */
+  listPage(options?: ListListViewsOptions): Promise<ListResult<ListView>>
+
+  /**
+   * Gets a single list view by slug.
+   *
+   * @param slug - List view slug
+   * @returns The list view
+   * @throws {ProteosError} If list view not found (404)
+   */
+  get(slug: string): Promise<ListView>
+
+  /**
+   * Creates a new list view.
+   *
+   * @param request - List view creation request
+   * @returns The created list view
+   * @throws {ProteosError} If validation fails (400) or conflict (409)
+   */
+  create(request: CreateListViewRequest): Promise<ListView>
+
+  /**
+   * Creates or updates a list view (upsert operation).
+   *
+   * @param request - List view creation request
+   * @returns The created or updated list view
+   */
+  upsert(request: CreateListViewRequest): Promise<ListView>
+
+  /**
+   * Updates an existing list view.
+   *
+   * @param slug - List view slug
+   * @param request - Fields to update
+   * @returns The updated list view
+   * @throws {ProteosError} If list view not found (404) or validation fails (400)
+   */
+  update(slug: string, request: UpdateListViewRequest): Promise<ListView>
+
+  /**
+   * Deletes a list view.
+   *
+   * @param slug - List view slug
+   * @throws {ProteosError} If list view not found (404)
+   */
+  delete(slug: string): Promise<void>
+}
+
+/**
+ * Implementation of ListViewService.
+ */
+export class ListViewServiceImpl implements ListViewService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListListViewsOptions = {}): PageIterator<ListView, ListListViewsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListListViewsOptions = {}): Promise<ListResult<ListView>> {
+    return this.client.requestWithQuery<ListResult<ListView>>('GET', LIST_VIEWS_BASE_PATH, options)
+  }
+
+  async get(slug: string): Promise<ListView> {
+    return this.client.request<ListView>('GET', `${LIST_VIEWS_BASE_PATH}/${slug}`)
+  }
+
+  async create(request: CreateListViewRequest): Promise<ListView> {
+    return this.client.request<ListView>('POST', LIST_VIEWS_BASE_PATH, request)
+  }
+
+  async upsert(request: CreateListViewRequest): Promise<ListView> {
+    return this.client.request<ListView>('POST', `${LIST_VIEWS_BASE_PATH}/upsert`, request)
+  }
+
+  async update(slug: string, request: UpdateListViewRequest): Promise<ListView> {
+    return this.client.request<ListView>('PATCH', `${LIST_VIEWS_BASE_PATH}/${slug}`, request)
+  }
+
+  async delete(slug: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${LIST_VIEWS_BASE_PATH}/${slug}`)
+  }
+}

package/src/meta/lists.ts

@@ -0,0 +1,104 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type { CreateListRequest, List, ListListsOptions, UpdateListRequest } from './types.js'
+
+const LISTS_BASE_PATH = '/meta/v1/lists'
+
+/**
+ * Service for managing list configurations.
+ * Lists define how data is displayed in tabular format.
+ */
+export interface ListService {
+  /**
+   * Lists list configurations with optional filtering.
+   *
+   * @param options - Filter and pagination options
+   * @returns Async iterator over lists
+   */
+  list(options?: ListListsOptions): PageIterator<List, ListListsOptions>
+
+  /**
+   * Fetches a single page of lists.
+   */
+  listPage(options?: ListListsOptions): Promise<ListResult<List>>
+
+  /**
+   * Gets a single list by slug.
+   *
+   * @param slug - List slug
+   * @returns The list
+   * @throws {ProteosError} If list not found (404)
+   */
+  get(slug: string): Promise<List>
+
+  /**
+   * Creates a new list.
+   *
+   * @param request - List creation request
+   * @returns The created list
+   * @throws {ProteosError} If validation fails (400) or conflict (409)
+   */
+  create(request: CreateListRequest): Promise<List>
+
+  /**
+   * Creates or updates a list (upsert operation).
+   *
+   * @param request - List creation request
+   * @returns The created or updated list
+   */
+  upsert(request: CreateListRequest): Promise<List>
+
+  /**
+   * Updates an existing list.
+   *
+   * @param slug - List slug
+   * @param request - Fields to update
+   * @returns The updated list
+   * @throws {ProteosError} If list not found (404) or validation fails (400)
+   */
+  update(slug: string, request: UpdateListRequest): Promise<List>
+
+  /**
+   * Deletes a list.
+   *
+   * @param slug - List slug
+   * @throws {ProteosError} If list not found (404)
+   */
+  delete(slug: string): Promise<void>
+}
+
+/**
+ * Implementation of ListService.
+ */
+export class ListServiceImpl implements ListService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListListsOptions = {}): PageIterator<List, ListListsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListListsOptions = {}): Promise<ListResult<List>> {
+    return this.client.requestWithQuery<ListResult<List>>('GET', LISTS_BASE_PATH, options)
+  }
+
+  async get(slug: string): Promise<List> {
+    return this.client.request<List>('GET', `${LISTS_BASE_PATH}/${slug}`)
+  }
+
+  async create(request: CreateListRequest): Promise<List> {
+    return this.client.request<List>('POST', LISTS_BASE_PATH, request)
+  }
+
+  async upsert(request: CreateListRequest): Promise<List> {
+    return this.client.request<List>('POST', `${LISTS_BASE_PATH}/upsert`, request)
+  }
+
+  async update(slug: string, request: UpdateListRequest): Promise<List> {
+    return this.client.request<List>('PATCH', `${LISTS_BASE_PATH}/${slug}`, request)
+  }
+
+  async delete(slug: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${LISTS_BASE_PATH}/${slug}`)
+  }
+}

package/src/meta/menu-configurations.ts

@@ -0,0 +1,128 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateMenuConfigurationRequest,
+  ListMenuConfigurationsOptions,
+  MenuConfiguration,
+  UpdateMenuConfigurationRequest,
+} from './types.js'
+
+const MENU_CONFIGURATIONS_BASE_PATH = '/meta/v1/menu-configurations'
+
+/**
+ * Service for managing menu configurations.
+ * Menu configurations define the navigation structure of applications.
+ */
+export interface MenuConfigurationService {
+  /**
+   * Lists menu configurations with optional filtering.
+   *
+   * @param options - Filter and pagination options
+   * @returns Async iterator over menu configurations
+   */
+  list(
+    options?: ListMenuConfigurationsOptions,
+  ): PageIterator<MenuConfiguration, ListMenuConfigurationsOptions>
+
+  /**
+   * Fetches a single page of menu configurations.
+   */
+  listPage(options?: ListMenuConfigurationsOptions): Promise<ListResult<MenuConfiguration>>
+
+  /**
+   * Gets a single menu configuration by slug.
+   *
+   * @param slug - Menu configuration slug (author-controlled, kebab-case)
+   * @returns The menu configuration
+   * @throws {ProteosError} If menu configuration not found (404)
+   */
+  get(slug: string): Promise<MenuConfiguration>
+
+  /**
+   * Creates a new menu configuration.
+   *
+   * @param request - Menu configuration creation request
+   * @returns The created menu configuration
+   * @throws {ProteosError} If validation fails (400) or conflict (409)
+   */
+  create(request: CreateMenuConfigurationRequest): Promise<MenuConfiguration>
+
+  /**
+   * Creates or updates a menu configuration idempotently by slug.
+   *
+   * @param slug - Menu configuration slug
+   * @param request - Body
+   * @returns The created or updated menu configuration
+   */
+  upsert(slug: string, request: CreateMenuConfigurationRequest): Promise<MenuConfiguration>
+
+  /**
+   * Updates an existing menu configuration.
+   *
+   * @param slug - Menu configuration slug
+   * @param request - Fields to update
+   * @returns The updated menu configuration
+   * @throws {ProteosError} If menu configuration not found (404) or validation fails (400)
+   */
+  update(slug: string, request: UpdateMenuConfigurationRequest): Promise<MenuConfiguration>
+
+  /**
+   * Deletes a menu configuration.
+   *
+   * @param slug - Menu configuration slug
+   * @throws {ProteosError} If menu configuration not found (404)
+   */
+  delete(slug: string): Promise<void>
+}
+
+/**
+ * Implementation of MenuConfigurationService.
+ */
+export class MenuConfigurationServiceImpl implements MenuConfigurationService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    options: ListMenuConfigurationsOptions = {},
+  ): PageIterator<MenuConfiguration, ListMenuConfigurationsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(
+    options: ListMenuConfigurationsOptions = {},
+  ): Promise<ListResult<MenuConfiguration>> {
+    return this.client.requestWithQuery<ListResult<MenuConfiguration>>(
+      'GET',
+      MENU_CONFIGURATIONS_BASE_PATH,
+      options,
+    )
+  }
+
+  async get(slug: string): Promise<MenuConfiguration> {
+    return this.client.request<MenuConfiguration>('GET', `${MENU_CONFIGURATIONS_BASE_PATH}/${slug}`)
+  }
+
+  async create(request: CreateMenuConfigurationRequest): Promise<MenuConfiguration> {
+    return this.client.request<MenuConfiguration>('POST', MENU_CONFIGURATIONS_BASE_PATH, request)
+  }
+
+  async upsert(slug: string, request: CreateMenuConfigurationRequest): Promise<MenuConfiguration> {
+    return this.client.request<MenuConfiguration>(
+      'PUT',
+      `${MENU_CONFIGURATIONS_BASE_PATH}/${slug}`,
+      { ...request, slug },
+    )
+  }
+
+  async update(slug: string, request: UpdateMenuConfigurationRequest): Promise<MenuConfiguration> {
+    return this.client.request<MenuConfiguration>(
+      'PATCH',
+      `${MENU_CONFIGURATIONS_BASE_PATH}/${slug}`,
+      request,
+    )
+  }
+
+  async delete(slug: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${MENU_CONFIGURATIONS_BASE_PATH}/${slug}`)
+  }
+}

package/src/meta/modules.ts

@@ -0,0 +1,159 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type { DeployModuleRequest, ListModulesOptions, Module } from './types.js'
+
+const MODULES_BASE_PATH = '/meta/v1/modules'
+
+/**
+ * Service for managing WebAssembly modules.
+ * Modules contain business logic that runs in the Proteos runtime.
+ */
+export interface ModuleService {
+  /**
+   * Lists modules with optional filtering.
+   *
+   * @param options - Filter and pagination options
+   * @returns Async iterator over modules
+   */
+  list(options?: ListModulesOptions): PageIterator<Module, ListModulesOptions>
+
+  /**
+   * Fetches a single page of modules.
+   */
+  listPage(options?: ListModulesOptions): Promise<ListResult<Module>>
+
+  /**
+   * Gets a single module by slug.
+   *
+   * @param slug - Module slug
+   * @returns The module
+   * @throws {ProteosError} If module not found (404)
+   */
+  get(slug: string): Promise<Module>
+
+  /**
+   * Deploys a new module.
+   * Uploads a WASM file with metadata.
+   *
+   * @param request - Module metadata
+   * @param file - WASM file (File, Blob, or ArrayBuffer)
+   * @returns The deployed module
+   * @throws {ProteosError} If validation fails (400) or conflict (409)
+   *
+   * @example
+   * ```ts
+   * const wasmFile = new File([wasmBytes], 'module.wasm');
+   * const module = await service.deploy(
+   *   {
+   *     slug: 'my-module',
+   *     version: '1.0.0',
+   *     name: 'My Module',
+   *     description: 'A custom module',
+   *   },
+   *   wasmFile
+   * );
+   * ```
+   */
+  deploy(request: DeployModuleRequest, file: File | Blob | ArrayBuffer): Promise<Module>
+
+  /**
+   * Deletes a module.
+   *
+   * @param slug - Module slug
+   * @throws {ProteosError} If module not found (404)
+   */
+  delete(slug: string): Promise<void>
+
+  /**
+   * Activates a deactivated module.
+   *
+   * @param slug - Module slug
+   * @throws {ProteosError} If module not found (404)
+   */
+  activate(slug: string): Promise<void>
+
+  /**
+   * Deactivates an active module.
+   *
+   * @param slug - Module slug
+   * @throws {ProteosError} If module not found (404)
+   */
+  deactivate(slug: string): Promise<void>
+
+  /**
+   * Downloads the module WASM file.
+   *
+   * @param slug - Module slug
+   * @returns Object containing the readable stream and module metadata
+   * @throws {ProteosError} If module not found (404)
+   *
+   * @example
+   * ```ts
+   * const { body, module } = await service.download('my-module');
+   * const reader = body.getReader();
+   * // Read the stream...
+   * ```
+   */
+  download(slug: string): Promise<{ body: ReadableStream<Uint8Array> | null; module: Module }>
+}
+
+/**
+ * Implementation of ModuleService.
+ */
+export class ModuleServiceImpl implements ModuleService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListModulesOptions = {}): PageIterator<Module, ListModulesOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListModulesOptions = {}): Promise<ListResult<Module>> {
+    return this.client.requestWithQuery<ListResult<Module>>('GET', MODULES_BASE_PATH, options)
+  }
+
+  async get(slug: string): Promise<Module> {
+    return this.client.request<Module>('GET', `${MODULES_BASE_PATH}/${slug}`)
+  }
+
+  async deploy(request: DeployModuleRequest, file: File | Blob | ArrayBuffer): Promise<Module> {
+    const formData = new FormData()
+
+    // Add metadata as JSON string
+    formData.append('metadata', JSON.stringify(request))
+
+    // Add file
+    let blob: Blob
+    if (file instanceof ArrayBuffer) {
+      blob = new Blob([file], { type: 'application/wasm' })
+    } else {
+      blob = file
+    }
+    formData.append('file', blob, 'module.wasm')
+
+    return this.client.requestMultipart<Module>('POST', `${MODULES_BASE_PATH}/deploy`, formData)
+  }
+
+  async delete(slug: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${MODULES_BASE_PATH}/${slug}`)
+  }
+
+  async activate(slug: string): Promise<void> {
+    await this.client.request<void>('PATCH', `${MODULES_BASE_PATH}/${slug}/activate`)
+  }
+
+  async deactivate(slug: string): Promise<void> {
+    await this.client.request<void>('PATCH', `${MODULES_BASE_PATH}/${slug}/deactivate`)
+  }
+
+  async download(
+    slug: string,
+  ): Promise<{ body: ReadableStream<Uint8Array> | null; module: Module }> {
+    const [{ body }, module] = await Promise.all([
+      this.client.requestRaw('GET', `${MODULES_BASE_PATH}/${slug}/download`),
+      this.get(slug),
+    ])
+
+    return { body, module }
+  }
+}