@proteos/sdk 0.20.5 → 0.22.0

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,
@@ -441,12 +447,16 @@ export type {
   PageAction,
   PageLayout,
   PageService,
+  PageType,
+  PublicPageComponent,
+  PublicPageResponse,
   // Relation attribute meta
   RelationAttributeMeta,
   SortConfig,
   SortDirection,
   UpdateAppRequest,
   UpdateComponentRequest,
+  UpdateDesignReferenceRequest,
   UpdateEntityRequest,
   UpdateListRequest,
   UpdateListViewRequest,
@@ -470,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,
@@ -171,6 +184,9 @@ export type {
   // Page types
   Page,
   PageAction,
+  PageType,
+  PublicPageComponent,
+  PublicPageResponse,
   // Relation attribute meta
   RelationAttributeMeta,
   SortConfig,
@@ -179,6 +195,7 @@ export type {
   StringFormat,
   UpdateAppRequest,
   UpdateComponentRequest,
+  UpdateDesignReferenceRequest,
   UpdateEntityRequest,
   UpdateListRequest,
   UpdateListViewRequest,
@@ -198,6 +215,7 @@ export {
   ColumnSchema,
   ComponentSchema,
   CurrencyAttributeMetaSchema,
+  DesignReferenceSchema,
   EntitySchema,
   EntityWithSchemaSchema,
   FileAttributeMetaSchema,

package/src/meta/pages.ts

@@ -1,7 +1,13 @@
 import type { ProteosClient } from '../client.js'
 import { PageIterator } from '../iterator.js'
 import type { ListResult } from '../types/common.js'
-import type { CreatePageRequest, ListPagesOptions, Page, UpdatePageRequest } from './types.js'
+import type {
+  CreatePageRequest,
+  ListPagesOptions,
+  Page,
+  PublicPageResponse,
+  UpdatePageRequest,
+} from './types.js'
 
 const PAGES_BASE_PATH = '/meta/v1/pages'
 
@@ -32,6 +38,18 @@ export interface PageService {
    */
   get(slug: string): Promise<Page>
 
+  /**
+   * Gets a PUBLIC page (type='public') without authentication — no
+   * Authorization header is sent. Returns the page plus the props_schema of
+   * every component its layout references. Non-public pages 404
+   * (indistinguishable from absent).
+   *
+   * @param orgId - Org id (public routes carry the org in the path — there is
+   *   no token to scope from)
+   * @param slug - Page slug
+   */
+  getPublic(orgId: string, slug: string): Promise<PublicPageResponse>
+
   /**
    * Creates a new page.
    *
@@ -88,6 +106,15 @@ export class PageServiceImpl implements PageService {
     return this.client.request<Page>('GET', `${PAGES_BASE_PATH}/${slug}`)
   }
 
+  async getPublic(orgId: string, slug: string): Promise<PublicPageResponse> {
+    return this.client.request<PublicPageResponse>(
+      'GET',
+      `/meta/v1/public/orgs/${encodeURIComponent(orgId)}/pages/${encodeURIComponent(slug)}`,
+      undefined,
+      { skipAuth: true },
+    )
+  }
+
   async create(request: CreatePageRequest): Promise<Page> {
     return this.client.request<Page>('POST', PAGES_BASE_PATH, request)
   }

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
@@ -641,6 +668,13 @@ export interface Component extends AuditFields {
   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
+  /**
+   * Opts the compiled bundle into UNAUTHENTICATED serving. Public
+   * (type='public') pages may only reference public components (enforced at
+   * page save), and a public component's only platform reach at runtime is
+   * `functions.actions.invokePublic`.
+   */
+  is_public: boolean
 }
 
 export const ComponentSchema = AuditFieldsSchema.extend({
@@ -650,7 +684,9 @@ export const ComponentSchema = AuditFieldsSchema.extend({
   module_slug: z.string(),
   bundle_file_id: z.string(),
   source_file_id: z.string(),
+  // default(false): rows serialized before the flag existed lack the field.
   props_schema: z.record(z.unknown()).nullable(),
+  is_public: z.boolean().default(false),
 })
 
 /**
@@ -673,6 +709,8 @@ export interface CreateComponentRequest {
   bundle_file_id?: string
   source_file_id?: string
   props_schema?: Record<string, unknown>
+  /** See {@link Component.is_public}. Manifest-driven: omitting it sets false. */
+  is_public?: boolean
 }
 
 /**
@@ -684,6 +722,7 @@ export interface UpdateComponentRequest {
   bundle_file_id?: string
   source_file_id?: string
   props_schema?: Record<string, unknown>
+  is_public?: boolean
 }
 
 // ============================================================================
@@ -886,14 +925,21 @@ export const PageActionSchema = z.object({
 })
 
 /**
- * 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.
+ * Page type — encodes what the page binds to and how it is served (chrome +
+ * auth posture both follow from it):
+ *
+ * - `record`:   rendered against a single record of `entity_slug`; app chrome;
+ *   authenticated.
+ * - `platform`: standalone, no record context (e.g. a dashboard launched from
+ *   a menu item); app chrome; authenticated.
+ * - `kiosk`:    standalone, NO app chrome (bare page at `/k/…`); authenticated.
+ * - `public`:   standalone, NO app chrome (bare page at `/p/…`);
+ *   UNAUTHENTICATED — the layout is world-readable and its components may only
+ *   call `is_public` global actions.
  */
-export type PageType = 'record' | 'platform'
+export type PageType = 'record' | 'platform' | 'kiosk' | 'public'
 
-export const PageTypeSchema = z.enum(['record', 'platform'])
+export const PageTypeSchema = z.enum(['record', 'platform', 'kiosk', 'public'])
 
 /**
  * Page configuration. A `record` page is the detail-page shape for a single
@@ -924,6 +970,26 @@ export const PageSchema = AuditFieldsSchema.extend({
   layout: PageLayoutSchema,
 })
 
+/**
+ * Component metadata slice riding on the public page payload — just the slug
+ * and props schema (deliberately not the full Component: this is served
+ * unauthenticated).
+ */
+export interface PublicPageComponent {
+  slug: string
+  props_schema?: Record<string, unknown>
+}
+
+/**
+ * Payload of the unauthenticated `GET /meta/v1/public/orgs/{orgId}/pages/{slug}`:
+ * the page plus the props_schema of every component its layout references, so
+ * a public renderer needs no follow-up authenticated calls.
+ */
+export interface PublicPageResponse {
+  page: Page
+  components: PublicPageComponent[]
+}
+
 /**
  * Options for listing pages.
  */
@@ -1113,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`
+  }
 }