@proteos/sdk 0.21.0 → 0.22.1

package/src/index.ts

@@ -161,6 +161,23 @@ export {
 } from './auth/index.js'
 // Main client
 export { ProteosClient } from './client.js'
+export type {
+  ConnectionScope as ConnectorConnectionScope,
+  ConnectionStatus as ConnectorConnectionStatus,
+  ConnectionTokenResponse as ConnectorConnectionTokenResponse,
+  Connector,
+  ConnectorConnection,
+  ConnectorMethod,
+  CreateConnectorConnectionRequest,
+  CredentialKind as ConnectorCredentialKind,
+  InstallConnectorConnectionResponse,
+  ListConnectorConnectionsQuery,
+  ListConnectorsQuery,
+  UpdateConnectorConnectionRequest,
+  WriteCredentialsRequest,
+} from './connector/index.js'
+// Connector client (connector-service)
+export { ConnectorClient } from './connector/index.js'
 // Conversation types (conversation-service: connections, conversations, messages, listeners)
 export type {
   AgentListener,
@@ -190,17 +207,17 @@ export type {
   InstallConnectionResponse,
   ListAgentListenersQuery,
   ListConnectionsQuery,
-  ListGlossaryTermsQuery,
   ListConversationsQuery,
+  ListGlossaryTermsQuery,
   ListMessagesQuery,
   ListParticipantsQuery,
   // Conversation-local page envelope ({meta, data}) — distinct from the
   // PageIterator-based ListResult used by the other modules.
   ListResponse,
   ListRoomsQuery,
+  MeetingService,
   Message,
   MessageDirection,
-  MeetingService,
   MessagePreview,
   MessageRecipient,
   MessageService,
@@ -228,23 +245,6 @@ export type {
 } from './conversation/index.js'
 // Conversation client (conversation-service)
 export { ConversationClient } from './conversation/index.js'
-// Connector client (connector-service)
-export { ConnectorClient } from './connector/index.js'
-export type {
-  Connector,
-  ConnectorConnection,
-  ConnectorMethod,
-  ConnectionScope as ConnectorConnectionScope,
-  ConnectionStatus as ConnectorConnectionStatus,
-  ConnectionTokenResponse as ConnectorConnectionTokenResponse,
-  CreateConnectorConnectionRequest,
-  CredentialKind as ConnectorCredentialKind,
-  InstallConnectorConnectionResponse,
-  ListConnectorConnectionsQuery,
-  ListConnectorsQuery,
-  UpdateConnectorConnectionRequest,
-  WriteCredentialsRequest,
-} from './connector/index.js'
 export type {
   BatchTransactionError,
   BatchTransactionStatus,
@@ -390,6 +390,7 @@ export type {
   ComponentService,
   CreateAppRequest,
   CreateComponentRequest,
+  CreateDesignReferenceRequest,
   CreateEntityRequest,
   CreateListRequest,
   CreateListViewRequest,
@@ -401,6 +402,10 @@ export type {
   CurrencySymbolSide,
   CurrencyValue,
   DeployModuleRequest,
+  // DesignReference types
+  DesignReference,
+  DesignReferenceContent,
+  DesignReferenceService,
   // Entity types
   Entity,
   EntityService,
@@ -413,6 +418,7 @@ export type {
   List,
   ListAppsOptions,
   ListComponentsOptions,
+  ListDesignReferencesOptions,
   ListEntitiesOptions,
   ListListsOptions,
   ListListViewsOptions,
@@ -439,17 +445,18 @@ export type {
   // Page types
   Page,
   PageAction,
+  PageLayout,
+  PageService,
   PageType,
   PublicPageComponent,
   PublicPageResponse,
-  PageLayout,
-  PageService,
   // Relation attribute meta
   RelationAttributeMeta,
   SortConfig,
   SortDirection,
   UpdateAppRequest,
   UpdateComponentRequest,
+  UpdateDesignReferenceRequest,
   UpdateEntityRequest,
   UpdateListRequest,
   UpdateListViewRequest,
@@ -473,6 +480,7 @@ export {
   currencyLabel,
   currencySymbol,
   currencySymbolSide,
+  DesignReferenceSchema,
   EntitySchema,
   EntityWithSchemaSchema,
   FilterElementSchema,

package/src/meta/design-references.ts

@@ -0,0 +1,127 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateDesignReferenceRequest,
+  DesignReference,
+  DesignReferenceContent,
+  ListDesignReferencesOptions,
+  UpdateDesignReferenceRequest,
+} from './types.js'
+
+const DESIGN_REFERENCES_BASE_PATH = '/meta/v1/design-references'
+
+/**
+ * Service for managing an org's stored DESIGN.md documents (design references).
+ *
+ * The markdown body is split from the metadata methods: list/get never carry
+ * `content` — read it with {@link getContent} and write it with
+ * {@link setContent} (create may seed it in one shot).
+ */
+export interface DesignReferenceService {
+  /** Lists design references (metadata only — no `content`). */
+  list(
+    options?: ListDesignReferencesOptions,
+  ): PageIterator<DesignReference, ListDesignReferencesOptions>
+
+  /** Fetches a single page of design references (metadata only). */
+  listPage(options?: ListDesignReferencesOptions): Promise<ListResult<DesignReference>>
+
+  /** Gets a single design reference by id (metadata only — no `content`). */
+  get(id: string): Promise<DesignReference>
+
+  /** Resolves a design reference by its per-org slug (metadata only). */
+  getBySlug(slug: string): Promise<DesignReference>
+
+  /** Creates a design reference; `content` optionally seeds the body. */
+  create(request: CreateDesignReferenceRequest): Promise<DesignReference>
+
+  /** Creates or (by slug) replaces a design reference, including its body. */
+  upsert(request: CreateDesignReferenceRequest): Promise<DesignReference>
+
+  /** Updates a design reference's metadata (name/description/slug). */
+  update(id: string, request: UpdateDesignReferenceRequest): Promise<DesignReference>
+
+  /** Deletes a design reference. */
+  delete(id: string): Promise<void>
+
+  /** Reads the markdown body for a design reference. */
+  getContent(id: string): Promise<string>
+
+  /** Overwrites the markdown body for a design reference (metadata untouched). */
+  setContent(id: string, content: string): Promise<void>
+}
+
+/**
+ * Implementation of DesignReferenceService.
+ */
+export class DesignReferenceServiceImpl implements DesignReferenceService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    options: ListDesignReferencesOptions = {},
+  ): PageIterator<DesignReference, ListDesignReferencesOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListDesignReferencesOptions = {}): Promise<ListResult<DesignReference>> {
+    return this.client.requestWithQuery<ListResult<DesignReference>>(
+      'GET',
+      DESIGN_REFERENCES_BASE_PATH,
+      options,
+    )
+  }
+
+  async get(id: string): Promise<DesignReference> {
+    return this.client.request<DesignReference>('GET', `${DESIGN_REFERENCES_BASE_PATH}/${id}`)
+  }
+
+  async getBySlug(slug: string): Promise<DesignReference> {
+    const page = await this.listPage({ slug })
+    const match = page.data[0]
+    if (!match) {
+      throw new Error(`design reference with slug "${slug}" not found`)
+    }
+    return match
+  }
+
+  async create(request: CreateDesignReferenceRequest): Promise<DesignReference> {
+    return this.client.request<DesignReference>('POST', DESIGN_REFERENCES_BASE_PATH, request)
+  }
+
+  async upsert(request: CreateDesignReferenceRequest): Promise<DesignReference> {
+    return this.client.request<DesignReference>(
+      'POST',
+      `${DESIGN_REFERENCES_BASE_PATH}/upsert`,
+      request,
+    )
+  }
+
+  async update(id: string, request: UpdateDesignReferenceRequest): Promise<DesignReference> {
+    return this.client.request<DesignReference>(
+      'PATCH',
+      `${DESIGN_REFERENCES_BASE_PATH}/${id}`,
+      request,
+    )
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${DESIGN_REFERENCES_BASE_PATH}/${id}`)
+  }
+
+  async getContent(id: string): Promise<string> {
+    const response = await this.client.request<DesignReferenceContent>(
+      'GET',
+      `${DESIGN_REFERENCES_BASE_PATH}/${id}/content`,
+    )
+    return response.content
+  }
+
+  async setContent(id: string, content: string): Promise<void> {
+    await this.client.request<DesignReferenceContent>(
+      'PUT',
+      `${DESIGN_REFERENCES_BASE_PATH}/${id}/content`,
+      { content },
+    )
+  }
+}

package/src/meta/entities.ts

@@ -82,6 +82,13 @@ export interface EntityService {
    */
   getWithSchema(slug: string): Promise<EntityWithSchema>
 
+  /**
+   * Gets a public-access (read) entity (with schema) through the UNAUTHENTICATED
+   * public endpoint — no Authorization header. A non-public or missing
+   * entity 404s identically.
+   */
+  getPublic(orgId: string, slug: string): Promise<EntityWithSchema>
+
   /**
    * Creates a new entity.
    *
@@ -175,6 +182,16 @@ export class EntityServiceImpl implements EntityService {
     })
   }
 
+  async getPublic(orgId: string, slug: string): Promise<EntityWithSchema> {
+    return this.client.requestWithQuery<EntityWithSchema>(
+      'GET',
+      `/meta/v1/public/orgs/${encodeURIComponent(orgId)}/entities/${encodeURIComponent(slug)}`,
+      { with_schema: true },
+      undefined,
+      { skipAuth: true },
+    )
+  }
+
   async create(request: CreateEntityRequest): Promise<Entity> {
     return this.client.request<Entity>('POST', ENTITIES_BASE_PATH, request)
   }

package/src/meta/index.ts

@@ -1,6 +1,7 @@
 import type { ProteosClient } from '../client.js'
 import { type AppService, AppServiceImpl } from './apps.js'
 import { type ComponentService, ComponentServiceImpl } from './components.js'
+import { type DesignReferenceService, DesignReferenceServiceImpl } from './design-references.js'
 import { type EntityService, EntityServiceImpl } from './entities.js'
 import { type ListViewService, ListViewServiceImpl } from './list-views.js'
 import { type ListService, ListServiceImpl } from './lists.js'
@@ -78,6 +79,11 @@ export class MetaClient {
    */
   readonly apps: AppService
 
+  /**
+   * Service for managing design references (stored DESIGN.md documents).
+   */
+  readonly designReferences: DesignReferenceService
+
   /**
    * Creates a new MetaClient instance.
    *
@@ -93,12 +99,14 @@ export class MetaClient {
     this.pages = new PageServiceImpl(client)
     this.menuConfigurations = new MenuConfigurationServiceImpl(client)
     this.apps = new AppServiceImpl(client)
+    this.designReferences = new DesignReferenceServiceImpl(client)
   }
 }
 
 export type { AppService } from './apps.js'
 export type { ComponentService } from './components.js'
 export * from './currency/index.js'
+export type { DesignReferenceService } from './design-references.js'
 // Re-export service interfaces
 export type { EntityService } from './entities.js'
 // Re-export the layout module (PageLayout types + Zod schemas + control registry)
@@ -122,6 +130,7 @@ export type {
   Component,
   CreateAppRequest,
   CreateComponentRequest,
+  CreateDesignReferenceRequest,
   CreateEntityRequest,
   CreateListRequest,
   CreateListViewRequest,
@@ -134,6 +143,9 @@ export type {
   DatetimeAttributeMeta,
   DatetimeFormat,
   DeployModuleRequest,
+  // DesignReference types
+  DesignReference,
+  DesignReferenceContent,
   // Entity types
   Entity,
   EntityWithSchema,
@@ -147,6 +159,7 @@ export type {
   List,
   ListAppsOptions,
   ListComponentsOptions,
+  ListDesignReferencesOptions,
   ListEntitiesOptions,
   ListListsOptions,
   ListListViewsOptions,
@@ -182,6 +195,7 @@ export type {
   StringFormat,
   UpdateAppRequest,
   UpdateComponentRequest,
+  UpdateDesignReferenceRequest,
   UpdateEntityRequest,
   UpdateListRequest,
   UpdateListViewRequest,
@@ -201,6 +215,7 @@ export {
   ColumnSchema,
   ComponentSchema,
   CurrencyAttributeMetaSchema,
+  DesignReferenceSchema,
   EntitySchema,
   EntityWithSchemaSchema,
   FileAttributeMetaSchema,

package/src/meta/layout/index.ts

@@ -33,9 +33,13 @@ export {
   type TextVariant,
 } from './elements.js'
 export {
+  PAGE_BACKGROUND_TOKENS,
+  type PageBackgroundToken,
   type PageLayout,
   PageLayoutSchema,
   type PageLayoutSidePanel,
   PageLayoutSidePanelSchema,
+  type PageStyle,
+  PageStyleSchema,
 } from './page-layout.js'
 export { type SizeValue, SizeValueSchema } from './size-value.js'

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

@@ -18,6 +18,58 @@ export const PageLayoutSidePanelSchema = z.object({
   content: LayoutElementSchema,
 })
 
+/**
+ * Design-token keys a page background may name instead of a raw CSS color. The
+ * web resolver maps each to `var(--color-<key>)`. Keep in sync with
+ * `pageBackgroundTokens` in the metadata-service layout validator.
+ */
+export const PAGE_BACKGROUND_TOKENS = [
+  'bg',
+  'bg-2',
+  'bg-3',
+  'ink',
+  'ink-2',
+  'ink-3',
+  'ink-4',
+  'rule',
+  'rule-2',
+  'accent',
+  'accent-2',
+  'accent-ink',
+  'success',
+  'warning',
+  'danger',
+  'info',
+] as const
+
+export type PageBackgroundToken = (typeof PAGE_BACKGROUND_TOKENS)[number]
+
+/**
+ * Per-page presentation of a standalone page shell: background color plus the
+ * content container's max-width and side / top padding. Every field is
+ * optional; an omitted field falls back to the renderer default (the historical
+ * bg / 1200px / 24px-32px look). `max_width: "fill"` (or `"auto"`) with zero
+ * padding lets a component fill the page edge-to-edge.
+ *
+ * Honored only on `public` and `kiosk` pages in v1 (enforced server-side).
+ */
+export interface PageStyle {
+  /** Design-token key (see PAGE_BACKGROUND_TOKENS) or a raw CSS color. */
+  background?: string
+  /** Content max-width; `"fill"` / `"auto"` removes the cap. */
+  max_width?: SizeValue
+  /** Horizontal / vertical padding of the content container (Tailwind px/py). */
+  padding_x?: SizeValue
+  padding_y?: SizeValue
+}
+
+export const PageStyleSchema = z.object({
+  background: z.string().optional(),
+  max_width: SizeValueSchema.optional(),
+  padding_x: SizeValueSchema.optional(),
+  padding_y: SizeValueSchema.optional(),
+})
+
 /**
  * Top-level page layout. Replaces the legacy `mainContent` / `side_panel`
  * arrays of `PageSection`s with a single typed element tree.
@@ -26,10 +78,12 @@ export interface PageLayout {
   version: 1
   main: LayoutElement
   side_panel?: PageLayoutSidePanel
+  style?: PageStyle
 }
 
 export const PageLayoutSchema = z.object({
   version: z.literal(1),
   main: LayoutElementSchema,
   side_panel: PageLayoutSidePanelSchema.optional(),
+  style: PageStyleSchema.optional(),
 })

package/src/meta/types.ts

@@ -425,6 +425,15 @@ export function parseFileMeta(attr: Attribute): FileAttributeMeta | null {
   return parsed.success ? parsed.data : {}
 }
 
+/**
+ * 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
+ * `read` is honored on the platform today; `write`/`delete` are reserved.
+ */
+export type PublicAccessOperation = 'read' | 'write' | 'delete'
+
+export const PublicAccessOperationSchema = z.enum(['read', 'write', 'delete'])
+
 /**
  * Entity definition.
  * Note: Entity uses `slug` as its primary identifier, not `id`.
@@ -434,6 +443,14 @@ export interface Entity extends AuditFields {
   name: string
   description: string
   is_remote: boolean
+  /**
+   * Operations ALL records of the entity are exposed for on the
+   * unauthenticated public surface. Only `["read"]` is honored today (records
+   * become world-readable; the entity definition is implicitly readable so
+   * they can be interpreted); `write`/`delete` are reserved. Empty = private
+   * (default).
+   */
+  public_record_access: PublicAccessOperation[]
   module_slug: string
   /**
    * Liquid template that renders a human-readable title for an instance
@@ -453,6 +470,9 @@ export const EntitySchema = AuditFieldsSchema.extend({
   name: z.string(),
   description: z.string(),
   is_remote: z.boolean(),
+  // Default keeps older API responses (pre-`public_record_access` rollout)
+  // parsing cleanly.
+  public_record_access: z.array(PublicAccessOperationSchema).default([]),
   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
@@ -489,6 +509,12 @@ export interface CreateEntityRequest {
   slug: string
   name: string
   is_remote: boolean
+  /**
+   * Operations to expose all records of the entity for, unauthenticated (only
+   * `["read"]` accepted today). Full-replacement on upsert: an upsert without
+   * the field resets it to private.
+   */
+  public_record_access?: PublicAccessOperation[]
   module_slug: string
   description: string
   title_template?: string
@@ -501,6 +527,7 @@ export interface CreateEntityRequest {
 export interface UpdateEntityRequest {
   name?: string
   is_remote?: boolean
+  public_record_access?: PublicAccessOperation[]
   module_slug?: string
   description?: string
   title_template?: string
@@ -1152,3 +1179,70 @@ export interface UpdateAppRequest {
   description?: string
   icon_slug?: string
 }
+
+// ============================================================================
+// DesignReference Types
+// ============================================================================
+
+/**
+ * A stored DESIGN.md document — a named design reference an org authors and that
+ * design agents read as the source of truth for a surface. `name` + `description`
+ * are the selector ("which reference, and when to use it").
+ *
+ * `content` (the markdown body) is NOT returned by list/get — fetch it via
+ * {@link DesignReferenceService.getContent} and write it via `setContent`.
+ */
+export interface DesignReference extends AuditFields {
+  id: string
+  org_id: string
+  slug: string
+  name: string
+  description: string
+  /** The DESIGN.md body. Only present on the dedicated content endpoint; undefined on list/get. */
+  content?: string
+}
+
+export const DesignReferenceSchema = AuditFieldsSchema.extend({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  description: z.string(),
+  content: z.string().optional(),
+})
+
+/**
+ * Options for listing design references.
+ */
+export interface ListDesignReferencesOptions extends MetaListOptions {
+  id?: string
+  slug?: string
+  name?: string
+  description?: string
+}
+
+/**
+ * Request to create a design reference. `content` optionally seeds the body.
+ */
+export interface CreateDesignReferenceRequest {
+  slug: string
+  name: string
+  description?: string
+  content?: string
+}
+
+/**
+ * Request to update a design reference's metadata. Content is edited via the
+ * dedicated content endpoint, not here.
+ */
+export interface UpdateDesignReferenceRequest {
+  slug?: string
+  name?: string
+  description?: string
+}
+
+/**
+ * The markdown body, from GET/PUT /design-references/:id/content.
+ */
+export interface DesignReferenceContent {
+  content: string
+}

package/src/storage/files.ts

@@ -70,6 +70,19 @@ export interface FileService {
    * {@link FileService.createDownloadUrl} for browser click-to-download.
    */
   download(id: string): Promise<Blob>
+
+  /**
+   * Downloads the current version of a public-read file through the
+   * UNAUTHENTICATED public endpoint (no Authorization header). A non-public
+   * or missing file 404s identically.
+   */
+  downloadPublic(orgId: string, id: string): Promise<Blob>
+
+  /**
+   * Builds the unauthenticated public download URL for a public-read
+   * file — usable directly as an <img src> / <a href> on public pages.
+   */
+  publicDownloadUrl(orgId: string, id: string): string
 }
 
 /**
@@ -180,4 +193,22 @@ export class FileServiceImpl implements FileService {
     const { response } = await this.client.requestRaw('GET', `${FILES_BASE_PATH}/${id}/download`)
     return await response.blob()
   }
+
+  async downloadPublic(orgId: string, id: string): Promise<Blob> {
+    const { response } = await this.client.requestRaw(
+      'GET',
+      this.publicDownloadPath(orgId, id),
+      undefined,
+      { skipAuth: true },
+    )
+    return await response.blob()
+  }
+
+  publicDownloadUrl(orgId: string, id: string): string {
+    return `${this.client.baseUrl}${this.publicDownloadPath(orgId, id)}`
+  }
+
+  private publicDownloadPath(orgId: string, id: string): string {
+    return `/storage/v1/public/orgs/${encodeURIComponent(orgId)}/files/${encodeURIComponent(id)}/download`
+  }
 }

package/src/storage/types.ts

@@ -1,3 +1,5 @@
+import type { PublicAccessOperation } from '../meta/types.js'
+
 /**
  * A version of a stored file. Each file has one or more versions; the file's
  * `current_version` points at the latest. Size is carried here, not on the
@@ -27,6 +29,12 @@ export interface StorageFile {
   is_deleted: boolean
   is_persisted: boolean
   is_locked: boolean
+  /**
+   * Operations the file is exposed for on the unauthenticated public surface.
+   * Only `["read"]` is honored (download via the public route). Empty =
+   * private (default).
+   */
+  public_access: PublicAccessOperation[]
   created_at: string
   updated_at: string
 }
@@ -38,6 +46,8 @@ export interface StorageFile {
 export interface CreateFileMetadata {
   name: string
   content_type?: string
+  /** See {@link StorageFile.public_access}. Only `["read"]` accepted today. */
+  public_access?: PublicAccessOperation[]
 }
 
 /**