@proteos/sdk 0.44.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/conversation/index.ts

@@ -17,6 +17,10 @@ import type {
   CreateAgentListenerRequest,
   CreateConnectionRequest,
   CreateContactGroupRequest,
+  CreateContactRequest,
+  ContactRecordLink,
+  CreateContactRecordLinkRequest,
+  ListContactRecordLinksQuery,
   CreateConversationFilterRequest,
   CreateConversationTypeRequest,
   CreateGlossaryTermRequest,
@@ -282,9 +286,17 @@ class ConnectionServiceImpl implements ConnectionService {
 export interface ContactService {
   list(query?: ListContactsQuery): Promise<ListResponse<Contact>>
   get(id: string): Promise<Contact>
+  /** Manually mint a contact (sync dedup — 409 contact_address_taken on any owned address). */
+  create(request: CreateContactRequest): Promise<Contact>
   update(id: string, request: UpdateContactRequest): Promise<Contact>
   attachAddress(contactId: string, request: AttachContactAddressRequest): Promise<Contact>
   detachAddress(contactId: string, addressId: string): Promise<Contact>
+  /** Link the contact to a business record (bare edge; 409 contact_record_link_exists on duplicates). */
+  linkRecord(request: CreateContactRecordLinkRequest): Promise<ContactRecordLink>
+  /** Page contact→record edges by contact_id, or by entity_slug + record_id. */
+  listRecordLinks(query?: ListContactRecordLinksQuery): Promise<ListResponse<ContactRecordLink>>
+  getRecordLink(linkId: string): Promise<ContactRecordLink>
+  unlinkRecord(linkId: string): Promise<void>
   /** Fold source_contact_id into contactId (contactId wins). */
   merge(contactId: string, request: MergeContactsRequest): Promise<Contact>
   recordPermissionEvent(contactId: string, request: RecordPermissionEventRequest): Promise<Contact>
@@ -313,6 +325,10 @@ class ContactServiceImpl implements ContactService {
     )
   }
 
+  create(request: CreateContactRequest): Promise<Contact> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/contacts`, request)
+  }
+
   update(id: string, request: UpdateContactRequest): Promise<Contact> {
     return this.client.request(
       'PATCH',
@@ -336,6 +352,32 @@ class ContactServiceImpl implements ContactService {
     )
   }
 
+  linkRecord(request: CreateContactRecordLinkRequest): Promise<ContactRecordLink> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/contact-record-links`, request)
+  }
+
+  listRecordLinks(query: ListContactRecordLinksQuery = {}): Promise<ListResponse<ContactRecordLink>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/contact-record-links`,
+      query,
+    )
+  }
+
+  getRecordLink(linkId: string): Promise<ContactRecordLink> {
+    return this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/contact-record-links/${encodeURIComponent(linkId)}`,
+    )
+  }
+
+  unlinkRecord(linkId: string): Promise<void> {
+    return this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/contact-record-links/${encodeURIComponent(linkId)}`,
+    )
+  }
+
   merge(contactId: string, request: MergeContactsRequest): Promise<Contact> {
     return this.client.request(
       'POST',

package/src/conversation/types.ts

@@ -1252,6 +1252,16 @@ export interface UpdateContactRequest {
   group_key?: string
 }
 
+/**
+ * Manually mints a contact with at least one address. Addresses are
+ * canonicalized server-side; any address already owned by another contact
+ * rejects the create with 409 contact_address_taken.
+ */
+export interface CreateContactRequest {
+  name: string
+  addresses: AttachContactAddressRequest[]
+}
+
 export interface AttachContactAddressRequest {
   kind: ContactAddressKind
   scope?: string
@@ -1259,6 +1269,33 @@ export interface AttachContactAddressRequest {
   name?: string
 }
 
+/**
+ * A directed edge from a contact to a business record (entity_slug +
+ * record_id). Bare — no role; the relationship's semantics come from the
+ * target entity. Immutable once created.
+ */
+export interface ContactRecordLink {
+  id: string
+  org_id: string
+  contact_id: string
+  entity_slug: string
+  record_id: string
+  created_at: string
+  created_by: UserRef
+}
+
+export interface CreateContactRecordLinkRequest {
+  contact_id: string
+  entity_slug: string
+  record_id: string
+}
+
+export interface ListContactRecordLinksQuery extends PaginationQuery {
+  contact_id?: string
+  entity_slug?: string
+  record_id?: string
+}
+
 export interface MergeContactsRequest {
   source_contact_id: string
 }

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,