@proteos/sdk 0.44.0 → 0.46.0

package/src/knowledge/spaces.ts

@@ -0,0 +1,86 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateSpaceRequest,
+  KnowledgeSpace,
+  ListSpacesOptions,
+  UpdateSpaceRequest,
+} from './types.js'
+
+const SPACES_BASE_PATH = '/knowledge/v1/spaces'
+
+/**
+ * Service for knowledge spaces — the containers nodes live in.
+ *
+ * Every method is keyed by SLUG rather than id: a space's slug is half its
+ * primary key and is immutable, so there is no second identifier. To file a node
+ * into a space, set `space_slug` on the node (see `NodeService`).
+ *
+ * Granting access to a space is NOT done here — it goes through the shared
+ * `auth.shares` API, which routes `knowledge-spaces` to knowledge-service:
+ *
+ * ```ts
+ * await auth.shares.share('knowledge-spaces', 'engineering', { type: 'team', id: 'platform' }, 'read')
+ * ```
+ */
+export interface SpaceService {
+  /** Lists spaces as an async iterator (pages are 0-indexed). */
+  list(options?: ListSpacesOptions): PageIterator<KnowledgeSpace, ListSpacesOptions>
+
+  /** Fetches a single page of spaces. */
+  listPage(options?: ListSpacesOptions): Promise<ListResult<KnowledgeSpace>>
+
+  /** Gets a single space by slug. */
+  get(slug: string): Promise<KnowledgeSpace>
+
+  /** Creates a space. The slug is permanent. */
+  create(request: CreateSpaceRequest): Promise<KnowledgeSpace>
+
+  /** Updates a space's presentation. The slug cannot be changed. */
+  update(slug: string, request: UpdateSpaceRequest): Promise<KnowledgeSpace>
+
+  /**
+   * Deletes a space and its access grants.
+   *
+   * Refused with 409 `knowledge_space_not_empty` while any node still lives in
+   * it — deleting a space never deletes the knowledge inside it, and never
+   * silently makes it org-visible by unfiling it. Move or delete the nodes first.
+   */
+  delete(slug: string): Promise<void>
+}
+
+/**
+ * Implementation of SpaceService.
+ */
+export class SpaceServiceImpl implements SpaceService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListSpacesOptions = {}): PageIterator<KnowledgeSpace, ListSpacesOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListSpacesOptions = {}): Promise<ListResult<KnowledgeSpace>> {
+    return this.client.requestWithQuery<ListResult<KnowledgeSpace>>(
+      'GET',
+      SPACES_BASE_PATH,
+      options,
+    )
+  }
+
+  async get(slug: string): Promise<KnowledgeSpace> {
+    return this.client.request<KnowledgeSpace>('GET', `${SPACES_BASE_PATH}/${slug}`)
+  }
+
+  async create(request: CreateSpaceRequest): Promise<KnowledgeSpace> {
+    return this.client.request<KnowledgeSpace>('POST', SPACES_BASE_PATH, request)
+  }
+
+  async update(slug: string, request: UpdateSpaceRequest): Promise<KnowledgeSpace> {
+    return this.client.request<KnowledgeSpace>('PATCH', `${SPACES_BASE_PATH}/${slug}`, request)
+  }
+
+  async delete(slug: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${SPACES_BASE_PATH}/${slug}`)
+  }
+}

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"
+      ]
+    }
   }
 }