@proteos/sdk 0.45.0 → 0.46.0

package/src/auth/types.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod'
-import type { AuditFields, ListOptions } from '../types/common.js'
-import { AuditFieldsSchema } from '../types/common.js'
+
+import { type PrincipalRef, PrincipalRefSchema } from '../meta/types.js'
+import type { AuditFields, FileRef, ListOptions } from '../types/common.js'
+import { AuditFieldsSchema, FileRefSchema } from '../types/common.js'
 
 // ============================================================================
 // Shared Auth Types
@@ -21,7 +23,20 @@ export interface AuthListOptions extends ListOptions {
 /**
  * Permission level for entity access.
  */
-export type Permission = 'read' | 'write' | 'delete'
+export type Permission =
+  | 'read'
+  | 'write'
+  | 'delete'
+  // Scoped twins. The grant a role holds decides how much it sees: `read` means
+  // every record of the entity in the org, `read_scoped` means only those whose
+  // access grants intersect the caller's principals (owned by them, owned by a
+  // team they are in, shared with them, or org-wide).
+  //
+  // The verbs stay independent, so `read` + `write_scoped` reads as "see every
+  // deal, edit only your own".
+  | 'read_scoped'
+  | 'write_scoped'
+  | 'delete_scoped'
 
 /**
  * Role entity permission - permission granted to a role for a specific entity.
@@ -38,7 +53,7 @@ export const RoleEntityPermissionSchema = AuditFieldsSchema.extend({
   id: z.string(),
   role_slug: z.string(),
   entity_slug: z.string(),
-  permission: z.enum(['read', 'write', 'delete']),
+  permission: z.enum(['read', 'write', 'delete', 'read_scoped', 'write_scoped', 'delete_scoped']),
 })
 
 /**
@@ -94,6 +109,17 @@ export interface ListUserRoleAssignmentsOptions extends AuthListOptions {
   role_slug?: string
 }
 
+/**
+ * Options for the org-wide assignment listing (`GET /user-role-assignments`).
+ * Unlike {@link ListUserRoleAssignmentsOptions} (which is bound to one user via
+ * the path), this one may also filter by `user_id`.
+ */
+export interface ListOrgUserRoleAssignmentsOptions extends AuthListOptions {
+  id?: string
+  user_id?: string
+  role_slug?: string
+}
+
 // ============================================================================
 // User Types
 // ============================================================================
@@ -108,6 +134,11 @@ export interface User extends AuditFields {
   family_name: string
   external_id: string
   default_org_id: string
+  /**
+   * Reference to the user's photo in the storage-service. Absent/null = no
+   * photo (clients render initials).
+   */
+  profile_image?: FileRef | null
 }
 
 export const UserSchema = AuditFieldsSchema.extend({
@@ -117,6 +148,7 @@ export const UserSchema = AuditFieldsSchema.extend({
   family_name: z.string(),
   external_id: z.string(),
   default_org_id: z.string(),
+  profile_image: FileRefSchema.nullish(),
 })
 
 /**
@@ -136,6 +168,23 @@ export interface UpdateUserRequest {
   given_name?: string
   family_name?: string
   default_org_id?: string
+  /**
+   * Tri-state: omit = leave unchanged, `null` = remove the photo, a FileRef =
+   * set it. Upload the file to the storage-service first and reference it here.
+   */
+  profile_image?: FileRef | null
+}
+
+/**
+ * Caller-scoped `PATCH /me` body. Deliberately narrower than
+ * {@link UpdateUserRequest}: a user may edit their own name and photo, but not
+ * re-home their account (no `default_org_id`).
+ */
+export interface UpdateMeRequest {
+  given_name?: string
+  family_name?: string
+  /** Tri-state — see {@link UpdateUserRequest.profile_image}. */
+  profile_image?: FileRef | null
 }
 
 /**
@@ -249,6 +298,103 @@ export interface ListRolesOptions extends AuthListOptions {
   description?: string
 }
 
+// ============================================================================
+// Team Types
+// ============================================================================
+
+/**
+ * A team — a node in the org's structure, and a principal that can hold access
+ * anywhere a user can.
+ *
+ * Hierarchy rolls UP: a member of a child team counts as a member of every
+ * ancestor **for grants made to that ancestor**. Granting `sales` reaches the
+ * members of `sales-emea`; granting `sales-emea` never reaches someone who is
+ * only in `sales`.
+ *
+ * The slug is immutable — it is half the primary key, and grants reference
+ * `team:<orgId>/<slug>`.
+ */
+export interface Team extends AuditFields {
+  slug: string
+  name: string
+  org_id: string
+  description: string
+  /** This team's parent within the same org; empty for a root team. */
+  parent_team_slug: string
+}
+
+export const TeamSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  name: z.string(),
+  org_id: z.string(),
+  description: z.string(),
+  parent_team_slug: z.string(),
+})
+
+/**
+ * One user's DIRECT membership of one team. Membership of ancestor teams is
+ * derived rather than stored, so it never appears as a row here.
+ */
+export interface TeamMember extends AuditFields {
+  id: string
+  org_id: string
+  team_slug: string
+  user_id: string
+}
+
+export const TeamMemberSchema = AuditFieldsSchema.extend({
+  id: z.string(),
+  org_id: z.string(),
+  team_slug: z.string(),
+  user_id: z.string(),
+})
+
+/**
+ * Request to create a team.
+ */
+export interface CreateTeamRequest {
+  org_id?: string
+  slug: string
+  name: string
+  description?: string
+  /** Nests the team under an existing one in the same org. Omit for a root. */
+  parent_team_slug?: string
+}
+
+/**
+ * Request to update a team.
+ *
+ * `slug` is deliberately absent: it is half the primary key and is referenced by
+ * every grant as `team:<orgId>/<slug>`, so renaming would orphan them.
+ */
+export interface UpdateTeamRequest {
+  name?: string
+  description?: string
+  /** Re-parents the team; an explicit empty string promotes it to a root. */
+  parent_team_slug?: string
+}
+
+export interface ListTeamsOptions extends AuthListOptions {
+  org_id?: string
+  slug?: string
+  name?: string
+  description?: string
+  parent_team_slug?: string
+}
+
+/**
+ * Request to add a user to a team.
+ */
+export interface AddTeamMemberRequest {
+  user_id: string
+}
+
+export interface ListTeamMembersOptions extends AuthListOptions {
+  org_id?: string
+  team_slug?: string
+  user_id?: string
+}
+
 // ============================================================================
 // Organization Types
 // ============================================================================
@@ -292,3 +438,45 @@ export interface ListOrganizationsOptions extends AuthListOptions {
   name?: string
   description?: string
 }
+
+/**
+ * The verbs a share can grant. Only these three — a typo'd permission is
+ * rejected rather than accepted as a grant that confers nothing.
+ */
+export type SharePermission = 'read' | 'write' | 'delete'
+
+/**
+ * The wire shape of a share write. Identical for granting and revoking, and
+ * shaped like the grant it produces, so ONE endpoint per owning service serves
+ * every entity rather than one endpoint per entity.
+ */
+export interface ShareRequest {
+  entity_slug: string
+  record_id: string
+  principal: PrincipalRef
+  permission: SharePermission
+}
+
+export const SharePermissionSchema = z.enum(['read', 'write', 'delete'])
+
+/**
+ * One stored share: a principal holding one verb on one record, with the
+ * grantor as provenance. Every row is an explicit share — ownership and
+ * granting attributes are evaluated live and never stored.
+ */
+export interface ShareRow {
+  entity_slug: string
+  record_id: string
+  /** Rendered principal string: `user:<id>` | `team:<orgId>/<slug>` | `org:<orgId>`. */
+  principal: string
+  permission: SharePermission
+  created_by?: { type: string; id: string }
+  created_at?: string
+}
+
+export const ShareRequestSchema = z.object({
+  entity_slug: z.string(),
+  record_id: z.string(),
+  principal: PrincipalRefSchema,
+  permission: SharePermissionSchema,
+})

package/src/auth/user-role-assignments.ts

@@ -0,0 +1,65 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type { ListOrgUserRoleAssignmentsOptions, UserRoleAssignment } from './types.js'
+
+const USER_ROLE_ASSIGNMENTS_BASE_PATH = '/accounts/v1/user-role-assignments'
+
+/**
+ * Service for the org-wide user-role-assignment listing.
+ *
+ * One request answers "who holds which role" across the whole org — the admin
+ * view joining users to their roles (role badges on a user list, a role's
+ * member roster, member counts) without a per-user fan-out. Per-user reads and
+ * writes stay on {@link UserService} (`users.getRoles` / `assignRole` /
+ * `unassignRole`).
+ */
+export interface UserRoleAssignmentService {
+  /**
+   * Lists role assignments across all users of the caller's org.
+   * Returns an async iterator that automatically handles pagination.
+   *
+   * @param options - Filter and pagination options (`role_slug`, `user_id`)
+   * @returns Async iterator over user role assignments
+   *
+   * @example
+   * ```ts
+   * // Everyone holding the sales role
+   * const sales = await service.list({ role_slug: 'sales' }).all();
+   * ```
+   */
+  list(
+    options?: ListOrgUserRoleAssignmentsOptions,
+  ): PageIterator<UserRoleAssignment, ListOrgUserRoleAssignmentsOptions>
+
+  /**
+   * Fetches a single page of role assignments.
+   *
+   * @param options - Filter and pagination options (including `page`)
+   * @returns A single page of assignments with pagination metadata
+   */
+  listPage(options?: ListOrgUserRoleAssignmentsOptions): Promise<ListResult<UserRoleAssignment>>
+}
+
+/**
+ * Implementation of UserRoleAssignmentService.
+ */
+export class UserRoleAssignmentServiceImpl implements UserRoleAssignmentService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    options: ListOrgUserRoleAssignmentsOptions = {},
+  ): PageIterator<UserRoleAssignment, ListOrgUserRoleAssignmentsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(
+    options: ListOrgUserRoleAssignmentsOptions = {},
+  ): Promise<ListResult<UserRoleAssignment>> {
+    return this.client.requestWithQuery<ListResult<UserRoleAssignment>>(
+      'GET',
+      USER_ROLE_ASSIGNMENTS_BASE_PATH,
+      options,
+    )
+  }
+}

package/src/index.ts

@@ -123,16 +123,25 @@ export type {
 export { AgentClient } from './agent/index.js'
 // Auth types (re-exported from auth/index.ts for convenience)
 export type {
+  AddTeamMemberRequest,
+  // Api key types
+  ApiKey,
   AssignPermissionRequest,
   AssignRoleRequest,
   // Shared auth types
   AuthListOptions,
+  CreateApiKeyRequest,
+  CreatedApiKey,
   CreateOrganizationRequest,
   CreateRoleRequest,
+  CreateTeamRequest,
   CreateUserRequest,
   ListOrganizationsOptions,
+  ListOrgUserRoleAssignmentsOptions,
   ListRolePermissionsOptions,
   ListRolesOptions,
+  ListTeamMembersOptions,
+  ListTeamsOptions,
   ListUserRoleAssignmentsOptions,
   ListUsersOptions,
   // Me (caller-scoped) service
@@ -148,13 +157,23 @@ export type {
   Role,
   RoleEntityPermission,
   RoleService,
+  Team,
+  TeamMember,
+  TeamService,
+  UpdateMeRequest,
   UpdateOrganizationRequest,
   UpdateRoleRequest,
+  UpdateTeamRequest,
   UpdateUserRequest,
+  // Share types (instance-level access)
+  SharePermission,
+  ShareRow,
+  ShareService,
   // User types
   User,
   // User role assignment types
   UserRoleAssignment,
+  UserRoleAssignmentService,
   UserService,
 } from './auth/index.js'
 // Auth client and services
@@ -162,11 +181,14 @@ export type {
 export {
   AccountClient,
   isPlatformEntity,
+  isShareable,
   OrganizationSchema,
   PLATFORM_ENTITIES,
   PLATFORM_ENTITY_SLUGS,
+  SCOPED_PLATFORM_ENTITY_SLUGS,
   RoleEntityPermissionSchema,
   RoleSchema,
+  shareRouteFor,
   UserRoleAssignmentSchema,
   UserSchema,
 } from './auth/index.js'
@@ -406,6 +428,7 @@ export type {
   CreateLinkRequest,
   CreateNodeRequest,
   CreateRecordLinkRequest,
+  CreateSpaceRequest,
   EditContentRequest,
   EditContentResponse,
   GetGraphOptions,
@@ -421,6 +444,7 @@ export type {
   KnowledgeNodeMetadata,
   KnowledgeNodeSearchResult,
   KnowledgeRecordLink,
+  KnowledgeSpace,
   LabelService,
   LinkService,
   LinkType,
@@ -428,6 +452,7 @@ export type {
   ListLinksOptions,
   ListNodesOptions,
   ListRecordLinksOptions,
+  ListSpacesOptions,
   MatchMode,
   NeighborDirection,
   NeighborEdge,
@@ -446,9 +471,11 @@ export type {
   SearchContentRequest,
   SearchContentResponse,
   SearchNodesRequest,
+  SpaceService,
   UpdateLabelRequest,
   UpdateLinkRequest,
   UpdateNodeRequest,
+  UpdateSpaceRequest,
   WriteContentResponse,
 } from './knowledge/index.js'
 // Knowledge client (knowledge-service: graph-native knowledge base)
@@ -462,6 +489,7 @@ export {
   KnowledgeNodeSearchResultSchema,
   KnowledgeRecordLinkSchema,
   NodeNeighborhoodSchema,
+  UNASSIGNED_SPACE_SLUG,
 } from './knowledge/index.js'
 // Meta types (re-exported from meta/index.ts for convenience)
 export type {
@@ -471,6 +499,10 @@ export type {
   // Array/enum attribute metas (config_schema renderers narrow on these)
   ArrayAttributeMeta,
   Attribute,
+  CurrentUserDefault,
+  // Attribute-level access restrictions (read/write allow-lists of role + team slugs)
+  AttributeAccessRule,
+  AttributeRestrictions,
   AttributeType,
   Column,
   ComparisonOperator,
@@ -536,6 +568,7 @@ export type {
   // Page types
   Page,
   PageAction,
+  PageActionKind,
   PageLayout,
   PageService,
   PageType,
@@ -580,6 +613,9 @@ export {
   formatAmount,
   formatMoney,
   isPlatformAttributeName,
+  CURRENT_USER_DEFAULT,
+  acceptsCurrentUserDefault,
+  isCurrentUserDefault,
   ListSchema,
   ListViewSchema,
   localeNumberSeparators,

package/src/knowledge/graph.ts

@@ -11,7 +11,8 @@ const GRAPH_BASE_PATH = '/knowledge/v1/graph'
 export interface GraphService {
   /**
    * Reads the whole org graph in one payload. `options.label_ids` prunes to
-   * nodes carrying ANY of the given labels (union); omitted returns everything.
+   * nodes carrying ANY of the given labels (union) and `options.space_slugs` to
+   * nodes in ANY of the given spaces; omitted returns everything.
    */
   get(options?: GetGraphOptions): Promise<KnowledgeGraph>
 }
@@ -26,10 +27,13 @@ export class GraphServiceImpl implements GraphService {
     // The server reads label_ids as a single comma-separated query param (the
     // query binder takes only the first value of a repeated param), so the
     // union list is joined here rather than appended as repeated params.
-    const query: { label_ids?: string } = {}
+    const query: { label_ids?: string; space_slugs?: string } = {}
     if (options.label_ids && options.label_ids.length > 0) {
       query.label_ids = options.label_ids.join(',')
     }
+    if (options.space_slugs && options.space_slugs.length > 0) {
+      query.space_slugs = options.space_slugs.join(',')
+    }
     return this.client.requestWithQuery<KnowledgeGraph>('GET', GRAPH_BASE_PATH, query)
   }
 }

package/src/knowledge/index.ts

@@ -3,6 +3,7 @@ import { type GraphService, GraphServiceImpl } from './graph.js'
 import { type LabelService, LabelServiceImpl } from './labels.js'
 import { type LinkService, LinkServiceImpl } from './links.js'
 import { type NodeService, NodeServiceImpl } from './nodes.js'
+import { type SpaceService, SpaceServiceImpl } from './spaces.js'
 import { type RecordLinkService, RecordLinkServiceImpl } from './record-links.js'
 
 /**
@@ -23,6 +24,11 @@ export class KnowledgeClient {
   /** Node→record edges (links to data-service records): `knowledge.recordLinks`. */
   readonly recordLinks: RecordLinkService
   readonly labels: LabelService
+  /**
+   * Knowledge spaces — the containers nodes live in: `knowledge.spaces`.
+   * Access to a space is granted through `auth.shares`, not here.
+   */
+  readonly spaces: SpaceService
   /** Whole-org graph bulk read (radiant graph view): `knowledge.graph.get()`. */
   readonly graph: GraphService
 
@@ -31,6 +37,7 @@ export class KnowledgeClient {
     this.links = new LinkServiceImpl(client)
     this.recordLinks = new RecordLinkServiceImpl(client)
     this.labels = new LabelServiceImpl(client)
+    this.spaces = new SpaceServiceImpl(client)
     this.graph = new GraphServiceImpl(client)
   }
 }
@@ -40,6 +47,7 @@ export type { GraphService } from './graph.js'
 export type { LabelService } from './labels.js'
 export type { LinkService } from './links.js'
 export type { NodeService } from './nodes.js'
+export type { SpaceService } from './spaces.js'
 export type { RecordLinkService } from './record-links.js'
 
 // Re-export types
@@ -50,6 +58,7 @@ export type {
   CreateLinkRequest,
   CreateNodeRequest,
   CreateRecordLinkRequest,
+  CreateSpaceRequest,
   EditContentRequest,
   EditContentResponse,
   GetGraphOptions,
@@ -64,11 +73,13 @@ export type {
   KnowledgeNodeMetadata,
   KnowledgeNodeSearchResult,
   KnowledgeRecordLink,
+  KnowledgeSpace,
   LinkType,
   ListLabelsOptions,
   ListLinksOptions,
   ListNodesOptions,
   ListRecordLinksOptions,
+  ListSpacesOptions,
   MatchMode,
   NeighborDirection,
   NeighborEdge,
@@ -88,9 +99,13 @@ export type {
   UpdateLabelRequest,
   UpdateLinkRequest,
   UpdateNodeRequest,
+  UpdateSpaceRequest,
   WriteContentResponse,
 } from './types.js'
 
+// Re-export the reserved space-filter sentinel (a value, not a type).
+export { UNASSIGNED_SPACE_SLUG } from './types.js'
+
 // Re-export Zod schemas
 export {
   KnowledgeLabelSchema,

package/src/knowledge/nodes.ts

@@ -100,11 +100,14 @@ export class NodeServiceImpl implements NodeService {
     // The server reads label_ids as a single comma-separated query param (the query
     // binder takes only the first value of a repeated param), so the union list is
     // joined here rather than appended as repeated params (mirrors GraphService.get).
-    const { label_ids, ...rest } = options
+    const { label_ids, space_slugs, ...rest } = options
     const query: Record<string, unknown> = { ...rest }
     if (label_ids && label_ids.length > 0) {
       query.label_ids = label_ids.join(',')
     }
+    if (space_slugs && space_slugs.length > 0) {
+      query.space_slugs = space_slugs.join(',')
+    }
     return this.client.requestWithQuery<ListResult<KnowledgeNodeMetadata>>(
       'GET',
       NODES_BASE_PATH,

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}`)
+  }
+}