@proteos/sdk 0.45.0 → 0.46.0

package/src/knowledge/types.ts

@@ -56,6 +56,12 @@ export interface KnowledgeNodeMetadata extends AuditFields {
   /** Embedding provenance (null until ingestion runs). */
   embedding_model?: string | null
   embedded_at?: string | null
+  /**
+   * The space this node lives in, or null when UNASSIGNED. An unassigned node
+   * is visible to anyone holding knowledge-nodes:read — the behaviour every
+   * node had before spaces existed.
+   */
+  space_slug?: string | null
   /** Source pointer for `file` nodes (storage-service file id). */
   file_id?: string | null
   /** Source pointer for `url` nodes. */
@@ -148,6 +154,8 @@ export interface CreateNodeRequest {
   type: NodeType
   status: NodeStatus
   content?: string
+  /** File the node into a space. Omitted = unassigned. */
+  space_slug?: string
   file_id?: string
   url?: string
   summary?: string
@@ -170,6 +178,12 @@ export interface UpdateNodeRequest {
    */
   valid_from?: string | null
   valid_until?: string | null
+  /**
+   * Move the node between spaces, tri-state like the validity window: omit to
+   * leave it where it is, pass `null` to move it back to unassigned, or a slug
+   * to file it into that space.
+   */
+  space_slug?: string | null
 }
 
 /** Filters for listing nodes. */
@@ -180,6 +194,11 @@ export interface ListNodesOptions extends ListOptions {
   'title[contains]'?: string
   /** Keep only nodes carrying ANY of these labels (union). */
   label_ids?: string[]
+  /**
+   * Keep only nodes living in ANY of these spaces (union). Use
+   * `UNASSIGNED_SPACE_SLUG` to ask for nodes belonging to no space.
+   */
+  space_slugs?: string[]
   /** Created on/after this RFC3339 timestamp (inclusive). */
   created_after?: string
   /** Created on/before this RFC3339 timestamp (inclusive). */
@@ -298,6 +317,11 @@ export interface SearchNodesRequest {
   status?: NodeStatus
   /** Match nodes carrying ANY of these labels. */
   label_ids?: string[]
+  /**
+   * Match nodes living in ANY of these spaces (union). Use
+   * `UNASSIGNED_SPACE_SLUG` for nodes belonging to no space.
+   */
+  space_slugs?: string[]
   /** Match nodes connected (either direction) to this node. */
   linked_to_id?: string
   /**
@@ -365,6 +389,8 @@ export interface KnowledgeGraphNode {
   type: NodeType
   status: NodeStatus
   label_ids: string[]
+  /** The node's space, or null when unassigned. */
+  space_slug?: string | null
   degree: number
 }
 
@@ -386,6 +412,12 @@ export interface KnowledgeGraph {
   nodes: KnowledgeGraphNode[]
   links: KnowledgeGraphLink[]
   labels: KnowledgeLabel[]
+  /**
+   * The full org space set, sent once for the same reason as `labels`: the
+   * client renders the space navigator and filters by space without a second
+   * request, even when the graph is pruned to one space.
+   */
+  spaces: KnowledgeSpace[]
   total: number
 }
 
@@ -395,6 +427,8 @@ export interface KnowledgeGraph {
  */
 export interface GetGraphOptions {
   label_ids?: string[]
+  /** Prune to nodes in ANY of these spaces (union). */
+  space_slugs?: string[]
 }
 
 // ============================================================================
@@ -443,6 +477,61 @@ export interface ListRecordLinksOptions extends ListOptions {
   record_id?: string
 }
 
+// ============================================================================
+// Spaces
+// ============================================================================
+
+/**
+ * A knowledge space: the container a node lives in. A node belongs to at most
+ * one space; a node with no space is unassigned.
+ *
+ * A space is NOT a label. Labels are many-per-node, overlapping, non-security
+ * tags; a space is the single place a node lives, and it is what instance-level
+ * access is evaluated against.
+ *
+ * Keyed by `slug`, which is IMMUTABLE — it is half the primary key, node rows
+ * reference it and access grants name it, so renaming would orphan both. There
+ * is no id.
+ */
+export interface KnowledgeSpace extends AuditFields {
+  org_id: string
+  slug: string
+  name: string
+  description?: string | null
+  color?: string | null
+  icon?: string | null
+}
+
+/**
+ * The reserved filter value meaning "nodes that belong to no space at all".
+ * Deliberately not a legal slug (slugs are kebab-case), so it can never collide
+ * with a space an org creates.
+ */
+export const UNASSIGNED_SPACE_SLUG = '__unassigned__'
+
+export interface CreateSpaceRequest {
+  /** Permanent — it is half the primary key and cannot be changed later. */
+  slug: string
+  name: string
+  description?: string
+  color?: string
+  icon?: string
+}
+
+/** Partial update. `slug` is absent because it is immutable. */
+export interface UpdateSpaceRequest {
+  name?: string
+  description?: string
+  color?: string
+  icon?: string
+}
+
+export interface ListSpacesOptions extends ListOptions {
+  slug?: string
+  name?: string
+  'name[contains]'?: string
+}
+
 // ============================================================================
 // Label requests
 // ============================================================================

package/src/meta/index.ts

@@ -123,6 +123,8 @@ export type {
   ArrayAttributeMeta,
   Attribute,
   AttributeMeta,
+  AttributeAccessRule,
+  AttributeRestrictions,
   AttributeType,
   Column,
   ComparisonOperator,
@@ -184,6 +186,7 @@ export type {
   // Page types
   Page,
   PageAction,
+  PageActionKind,
   PageType,
   PublicAccessOperation,
   PublicPageComponent,
@@ -204,6 +207,10 @@ export type {
   UpdatePageRequest,
   UpdateVariableRequest,
   // User attribute meta
+  PrincipalAttributeMeta,
+  CurrentUserDefault,
+  PrincipalRef,
+  PrincipalType,
   UserAttributeMeta,
   // Variable types
   Variable,
@@ -233,7 +240,11 @@ export {
   PageActionSchema,
   PageSchema,
   PLATFORM_ATTRIBUTE_NAMES,
+  CURRENT_USER_DEFAULT,
+  acceptsCurrentUserDefault,
+  isCurrentUserDefault,
   parseCurrencyMeta,
+  parsePrincipalMeta,
   parseFileMeta,
   parseRelationMeta,
   parseUserMeta,

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

@@ -1,7 +1,7 @@
 {
   "_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).",
+  "_attributeTypes": "Top-level keys MUST match the Go canonical AttributeType union in packages/go/model/meta/attribute.go (string \u00b7 number \u00b7 integer \u00b7 boolean \u00b7 array \u00b7 object \u00b7 datetime \u00b7 enum \u00b7 relation \u00b7 user \u00b7 currency \u00b7 knowledge-text \u00b7 file). `byFormat` keys for `string` MUST match StringFormat (email \u00b7 uri \u00b7 uuid \u00b7 hostname \u00b7 ipv4 \u00b7 ipv6). `byFormat` keys for `datetime` MUST match DatetimeFormat (date-time \u00b7 date \u00b7 time \u00b7 duration). `byItemsType` for `array` keys on the item Attribute's type. A null `primary` with empty `compatible` means \"render-only fallback\" \u2014 see plan \u00a73.2.5.",
+  "_slugRoster": "v1 ships only lib-backed slugs. Slugs without a backing @proteos/ui component (markdown \u00b7 json-editor \u00b7 slider \u00b7 stepper \u00b7 percent \u00b7 user-card) are intentionally omitted; they return when the matching lib primitive ships. See plan \u00a73.2.4 / \u00a77.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",
@@ -21,6 +21,7 @@
     "tag-input",
     "entity-picker",
     "user-picker",
+    "principal-picker",
     "currency",
     "knowledge-text",
     "file",
@@ -29,43 +30,167 @@
   "controls": {
     "string": {
       "primary": "text",
-      "compatible": ["text", "textarea", "password"],
+      "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"] }
+        "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"] },
+    "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"],
+      "compatible": [
+        "tag-input"
+      ],
       "byItemsType": {
-        "string": { "primary": "tag-input", "compatible": ["tag-input"] },
-        "enum": { "primary": "multi-select", "compatible": ["multi-select"] }
+        "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": [] }
+        "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", "file-viewer"] }
+    "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",
+        "file-viewer"
+      ]
+    },
+    "principal": {
+      "primary": "principal-picker",
+      "compatible": [
+        "principal-picker"
+      ]
+    }
   }
 }

package/src/meta/types.ts

@@ -38,10 +38,52 @@ export type AttributeType =
   | 'enum'
   | 'relation'
   | 'user'
+  | 'principal'
   | 'currency'
   | 'knowledge-text'
   | 'file'
 
+/**
+ * Attribute-level permissions: restricting a FIELD rather than a record — a
+ * salary column readable only by the people team, a margin column writable only
+ * by finance. Mirror of the Go `metamodel.AttributeRestrictions`.
+ *
+ * Orthogonal to instance-level access: a caller who may see a record may still
+ * be blocked from one of its fields.
+ *
+ * Absent means unrestricted. Both arms FAIL CLOSED — an empty rule matches
+ * nobody rather than everybody, and an unknown role or team slug never matches,
+ * so a typo removes access rather than granting it.
+ */
+export interface AttributeAccessRule {
+  /** Role slugs, matched against the caller's roles. */
+  roles?: string[]
+  /**
+   * Team slugs. Matched through the caller's team closure, so a member of a
+   * CHILD team is matched by a rule naming an ancestor.
+   */
+  teams?: string[]
+}
+
+export const AttributeAccessRuleSchema = z.object({
+  roles: z.array(z.string()).optional(),
+  teams: z.array(z.string()).optional(),
+})
+
+/**
+ * Read and write are gated independently, so `write` alone yields a field
+ * everyone can see and only some can change.
+ */
+export interface AttributeRestrictions {
+  read?: AttributeAccessRule
+  write?: AttributeAccessRule
+}
+
+export const AttributeRestrictionsSchema = z.object({
+  read: AttributeAccessRuleSchema.optional(),
+  write: AttributeAccessRuleSchema.optional(),
+})
+
 // ── Attribute meta (sub-discriminators) ──────────────────────────────
 // Mirrors the Go `*AttributeMeta` types in
 // packages/go/model/attribute-{string,number,datetime,array,object,enum}.go.
@@ -88,6 +130,10 @@ export interface EnumValue {
   value: string
   label?: string
   description?: string
+  /** Lucide icon name, canonical PascalCase (e.g. `CircleCheck`). Replaces the badge dot. */
+  icon?: string
+  /** Tint as `#rrggbb`. Renderers derive dot/border/background from it; text stays ink. */
+  color?: string
 }
 
 export interface EnumAttributeMeta {
@@ -144,6 +190,68 @@ export const UserAttributeMetaSchema = z.object({
   description: z.string().optional(),
 })
 
+/**
+ * The stored value of a `principal`-typed attribute: a {@link PrincipalRef}
+ * `{ type, id }` naming anything that can HOLD ACCESS — a user (person, agent
+ * or api client), a team, or the whole organization. Mirror of the Go
+ * `metamodel.PrincipalAttributeMeta`.
+ *
+ * Distinct from `user` on purpose. `user` means "a person did this" — it is
+ * authorship, and its value can never be a team. `principal` means "this party
+ * may be granted access", a different question with a strictly larger
+ * vocabulary. Widening `user` would have made every existing user attribute
+ * silently accept a team, including the created_by / updated_by audit columns.
+ */
+export interface PrincipalAttributeMeta {
+  description?: string
+  /**
+   * Turns the attribute into a GRANTING attribute: the verbs its value confers
+   * on the record. `deals.account_manager` with `["read","write"]` means setting
+   * it gives that principal access with no share call — the business field IS
+   * the ACL.
+   *
+   * `share` is the right to hand access on — share the record, set other
+   * granting attributes, revoke shares. `["read","write","delete","share"]` is
+   * full ownership: there is no separate owner field on the platform, the
+   * business field that grants `share` IS the owner. `share` must accompany
+   * at least one of read/write/delete, and an attribute granting it never
+   * accepts an `org` principal.
+   *
+   * Empty (the default) means an ordinary reference that confers nothing, so an
+   * existing principal attribute cannot start granting access by accident.
+   */
+  grants?: Array<'read' | 'write' | 'delete' | 'share'>
+  /**
+   * Narrows which principal kinds this attribute accepts; empty means all
+   * (except that an attribute granting `share` refuses `org` regardless —
+   * an org-wide right to re-grant would hand record management to every
+   * member).
+   */
+  allowed_types?: PrincipalType[]
+}
+
+export const PrincipalAttributeMetaSchema = z.object({
+  description: z.string().optional(),
+  grants: z.array(z.enum(['read', 'write', 'delete', 'share'])).optional(),
+  allowed_types: z.array(z.enum(['person', 'agent', 'api', 'team', 'org'])).optional(),
+})
+
+/** The kinds a principal reference may name. */
+export type PrincipalType = 'person' | 'agent' | 'api' | 'team' | 'org'
+
+/**
+ * The stored value of a `principal`-typed attribute.
+ */
+export interface PrincipalRef {
+  type: PrincipalType
+  id: string
+}
+
+export const PrincipalRefSchema = z.object({
+  type: z.enum(['person', 'agent', 'api', 'team', 'org']),
+  id: z.string(),
+})
+
 /**
  * The stored value of a `currency`-typed attribute: an exact decimal `amount`
  * (a STRING, never a JS number — preserves financial-system precision and
@@ -236,6 +344,7 @@ export type AttributeMeta =
   | EnumAttributeMeta
   | RelationAttributeMeta
   | UserAttributeMeta
+  | PrincipalAttributeMeta
   | CurrencyAttributeMeta
   | KnowledgeTextAttributeMeta
   | FileAttributeMeta
@@ -259,6 +368,17 @@ export interface Attribute {
    * Mirrors `IsPlatformManaged` in the Go `metamodel.Attribute`.
    */
   is_platform_managed?: boolean
+  /**
+   * Attribute-level permissions. Absent means unrestricted (today's behaviour).
+   * Platform-managed attributes cannot carry restrictions.
+   */
+  restrictions?: AttributeRestrictions
+  /**
+   * Literal default, or — on a `user` / `principal` attribute only — the
+   * current-user sentinel `{ type: 'current_user' }` (see
+   * `CURRENT_USER_DEFAULT`), which data-service resolves to the writer at
+   * record-write time.
+   */
   default_value?: unknown
   /**
    * Type-specific metadata. The concrete shape is determined by `type`
@@ -365,6 +485,7 @@ export const AttributeSchema = z.object({
   is_nullable: z.boolean().optional(),
   is_unique: z.boolean(),
   is_read_only: z.boolean().optional(),
+  restrictions: AttributeRestrictionsSchema.optional(),
   default_value: z.unknown().optional(),
   meta: z.unknown().optional(),
   options: z.record(z.unknown()).optional(),
@@ -393,6 +514,18 @@ export function parseCurrencyMeta(attr: Attribute): CurrencyAttributeMeta | null
   return parsed.success ? parsed.data : null
 }
 
+/**
+ * Returns the typed `PrincipalAttributeMeta` when `attr` is a principal
+ * attribute; null otherwise. Principal meta is optional, so an attribute with
+ * no meta resolves to an empty `{}` rather than null.
+ */
+export function parsePrincipalMeta(attr: Attribute): PrincipalAttributeMeta | null {
+  if (attr.type !== 'principal') return null
+  if (attr.meta == null) return {}
+  const parsed = PrincipalAttributeMetaSchema.safeParse(attr.meta)
+  return parsed.success ? parsed.data : {}
+}
+
 export function parseUserMeta(attr: Attribute): UserAttributeMeta | null {
   if (attr.type !== 'user') return null
   if (attr.meta == null) return {}
@@ -915,19 +1048,41 @@ export interface UpdateListViewRequest {
 // ============================================================================
 
 /**
- * Page action definition. Page-level toolbar item; addressed by permissions
- * and shortcuts systems.
+ * What a page toolbar button invokes. Absent normalizes to `action` (pages
+ * persisted before `kind` existed).
+ */
+export type PageActionKind = 'action' | 'workflow'
+
+/**
+ * Page action definition — one toolbar button. `kind: action` invokes a
+ * function-service Action by slug (`action`) and may prefill its params;
+ * `kind: workflow` starts a manual run of a workflow by key (`workflow`) and
+ * may prefill its manual-trigger inputs. `params` / `inputs` map target field
+ * names to Liquid templates rendered against the page scope
+ * `{ record, entity, params, user }`; a resolved field is locked in the invoke
+ * dialog. `skip_confirmation` fires the target immediately when every required
+ * field resolved from the templates.
  */
 export interface PageAction {
   label: string
   icon: string
-  action: string
+  kind?: PageActionKind
+  action?: string
+  workflow?: string
+  params?: Record<string, string>
+  inputs?: Record<string, string>
+  skip_confirmation?: boolean
 }
 
 export const PageActionSchema = z.object({
   label: z.string(),
   icon: z.string(),
-  action: z.string(),
+  kind: z.enum(['action', 'workflow']).optional(),
+  action: z.string().optional(),
+  workflow: z.string().optional(),
+  params: z.record(z.string()).optional(),
+  inputs: z.record(z.string()).optional(),
+  skip_confirmation: z.boolean().optional(),
 })
 
 /**
@@ -1252,3 +1407,30 @@ export interface UpdateDesignReferenceRequest {
 export interface DesignReferenceContent {
   content: string
 }
+
+/* -------------------------------------------------------------------------
+   Default-value sentinel
+   ------------------------------------------------------------------------- */
+
+/**
+ * The one non-literal `default_value`: "whoever is writing the record".
+ * Meaningful only on `user` and `principal` attributes, where data-service
+ * resolves it to the caller's `{ type, id }` at write time — an owner field
+ * granting `share`, an `assignee`, a `requested_by` fill themselves without a
+ * hook. An object rather than a bare string because a bare string IS a valid
+ * user value (clients send bare ids). Mirrors `metamodel.CurrentUserDefault`.
+ */
+export const CURRENT_USER_DEFAULT = { type: 'current_user' } as const
+export type CurrentUserDefault = { type: 'current_user' }
+
+/** True when a `default_value` is the current-user sentinel (and nothing else). */
+export function isCurrentUserDefault(value: unknown): value is CurrentUserDefault {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const keys = Object.keys(value)
+  return keys.length === 1 && (value as { type?: unknown }).type === 'current_user'
+}
+
+/** Only the identity-valued attribute types can carry the sentinel. */
+export function acceptsCurrentUserDefault(type: AttributeType): boolean {
+  return type === 'user' || type === 'principal'
+}