@proteos/sdk 0.21.0 → 0.22.0

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/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[]
 }
 
 /**