@proteos/sdk 0.45.0 → 0.46.0

package/src/auth/index.ts

@@ -2,6 +2,12 @@ import type { ProteosClient } from '../client.js'
 import { type MeService, MeServiceImpl } from './me.js'
 import { type OrganizationService, OrganizationServiceImpl } from './organizations.js'
 import { type RoleService, RoleServiceImpl } from './roles.js'
+import { type ShareService, ShareServiceImpl } from './shares.js'
+import { type TeamService, TeamServiceImpl } from './teams.js'
+import {
+  type UserRoleAssignmentService,
+  UserRoleAssignmentServiceImpl,
+} from './user-role-assignments.js'
 import { type UserService, UserServiceImpl } from './users.js'
 
 /**
@@ -41,11 +47,32 @@ export class AccountClient {
    */
   readonly roles: RoleService
 
+  /**
+   * Service for the org-wide user-role-assignment listing ("who holds which
+   * role" in one request).
+   */
+  readonly userRoleAssignments: UserRoleAssignmentService
+
   /**
    * Service for managing organizations.
    */
   readonly organizations: OrganizationService
 
+  /**
+   * Service for managing teams and their membership.
+   */
+  readonly teams: TeamService
+
+  /**
+   * Service for sharing individual resources with a principal.
+   *
+   * Lives here rather than on the owning resource's client because sharing is
+   * ONE concept across every resource type — a deal, a conversation, a
+   * knowledge space. Callers name an entity; which service handles the write is
+   * the SDK's problem, so centralizing it server-side later moves no caller.
+   */
+  readonly shares: ShareService
+
   /**
    * Creates a new AccountClient instance.
    *
@@ -55,7 +82,10 @@ export class AccountClient {
     this.me = new MeServiceImpl(client)
     this.users = new UserServiceImpl(client)
     this.roles = new RoleServiceImpl(client)
+    this.userRoleAssignments = new UserRoleAssignmentServiceImpl(client)
     this.organizations = new OrganizationServiceImpl(client)
+    this.teams = new TeamServiceImpl(client)
+    this.shares = new ShareServiceImpl(client)
   }
 }
 
@@ -63,12 +93,20 @@ export type { MeService } from './me.js'
 export type { OrganizationService } from './organizations.js'
 // Re-export platform entities (canonical mirror of the Go registry)
 export type { PlatformEntity } from './platform-entities.js'
-export { isPlatformEntity, PLATFORM_ENTITIES, PLATFORM_ENTITY_SLUGS } from './platform-entities.js'
+export {
+  isPlatformEntity,
+  PLATFORM_ENTITIES,
+  PLATFORM_ENTITY_SLUGS,
+  SCOPED_PLATFORM_ENTITY_SLUGS,
+} from './platform-entities.js'
 export type { RoleService } from './roles.js'
+export type { TeamService } from './teams.js'
+export type { UserRoleAssignmentService } from './user-role-assignments.js'
 // Re-export types
 export type {
   // Api key types
   ApiKey,
+  AddTeamMemberRequest,
   AssignPermissionRequest,
   AssignRoleRequest,
   // Shared types
@@ -77,10 +115,14 @@ export type {
   CreatedApiKey,
   CreateOrganizationRequest,
   CreateRoleRequest,
+  CreateTeamRequest,
   CreateUserRequest,
   ListOrganizationsOptions,
   ListRolePermissionsOptions,
   ListRolesOptions,
+  ListTeamMembersOptions,
+  ListTeamsOptions,
+  ListOrgUserRoleAssignmentsOptions,
   ListUserRoleAssignmentsOptions,
   ListUsersOptions,
   // Organization types
@@ -90,11 +132,20 @@ export type {
   // Role types
   Role,
   RoleEntityPermission,
+  // Team types
+  Team,
+  TeamMember,
+  UpdateMeRequest,
   UpdateOrganizationRequest,
   UpdateRoleRequest,
+  UpdateTeamRequest,
   UpdateUserRequest,
   // User types
   User,
+  // Share types
+  SharePermission,
+  ShareRequest,
+  ShareRow,
   // User role assignment types
   UserRoleAssignment,
 } from './types.js'
@@ -102,10 +153,16 @@ export type {
 export {
   ApiKeySchema,
   OrganizationSchema,
+  SharePermissionSchema,
+  ShareRequestSchema,
   RoleEntityPermissionSchema,
   RoleSchema,
+  TeamMemberSchema,
+  TeamSchema,
   UserRoleAssignmentSchema,
   UserSchema,
 } from './types.js'
 // Re-export service interfaces
 export type { UserService } from './users.js'
+// Share routing — exported so a UI can hide a share affordance it cannot serve.
+export { isShareable, type ShareService, shareRouteFor } from './shares.js'

package/src/auth/me.ts

@@ -1,5 +1,5 @@
 import type { ProteosClient } from '../client.js'
-import type { Organization, User } from './types.js'
+import type { Organization, UpdateMeRequest, User } from './types.js'
 
 const ME_BASE_PATH = '/accounts/v1/me'
 
@@ -17,6 +17,15 @@ export interface MeService {
    */
   get(): Promise<User>
 
+  /**
+   * Updates the caller's own profile (name, photo). Requires a JWT session —
+   * requests authenticated with an API key are rejected.
+   *
+   * @param request - Fields to update; `profile_image: null` removes the photo
+   * @returns The updated user
+   */
+  update(request: UpdateMeRequest): Promise<User>
+
   /**
    * Lists the organizations the caller can act in (all orgs for a platform
    * admin; otherwise the orgs they're a member of). Powers the org-switcher.
@@ -36,6 +45,10 @@ export class MeServiceImpl implements MeService {
     return this.client.request<User>('GET', ME_BASE_PATH)
   }
 
+  async update(request: UpdateMeRequest): Promise<User> {
+    return this.client.request<User>('PATCH', ME_BASE_PATH, request)
+  }
+
   async organizations(): Promise<Organization[]> {
     const response = await this.client.request<{ data: Organization[] }>(
       'GET',

package/src/auth/platform-entities.ts

@@ -22,6 +22,12 @@ export const PLATFORM_ENTITIES: readonly PlatformEntity[] = [
   { slug: 'roles', name: 'Roles' },
   { slug: 'user-role-assignments', name: 'User Role Assignments' },
   { slug: 'role-entity-permissions', name: 'Role Entity Permissions' },
+  // Teams are the org's structure and a principal that can hold access anywhere
+  // a user can. Membership is a separate slug: seeing the org chart and changing
+  // who is in it are different decisions, and membership is what moves access.
+  { slug: 'teams', name: 'Teams' },
+  { slug: 'team-members', name: 'Team Members' },
+  // The share audit trail — a distinct grant from the resources it references.
   // Schema / content (metadata-service)
   { slug: 'entities', name: 'Entities' },
   { slug: 'pages', name: 'Pages' },
@@ -47,6 +53,7 @@ export const PLATFORM_ENTITIES: readonly PlatformEntity[] = [
   { slug: 'knowledge-nodes', name: 'Knowledge Nodes' },
   { slug: 'knowledge-links', name: 'Knowledge Links' },
   { slug: 'knowledge-labels', name: 'Knowledge Labels' },
+  { slug: 'knowledge-spaces', name: 'Knowledge Spaces' },
   // Agent suite (agent-service)
   { slug: 'agents', name: 'Agents' },
   { slug: 'prompts', name: 'Prompts' },
@@ -70,6 +77,17 @@ export const PLATFORM_ENTITIES: readonly PlatformEntity[] = [
   { slug: 'glossary-terms', name: 'Glossary Terms' },
   // Mistranscribed terms proposed by the post-transcription review pass.
   { slug: 'mistranscribed-terms', name: 'Mistranscribed Terms' },
+  // The person-level identity layer (contacts + addresses + merges + consent +
+  // erasure) — one grant governs the whole aggregate.
+  { slug: 'contacts', name: 'Contacts' },
+  // Ingest-time filter rules + their drop-audit events.
+  { slug: 'conversation-filters', name: 'Conversation Filters' },
+  // The org's conversation taxonomy (read by the pre-summary classifier).
+  { slug: 'conversation-types', name: 'Conversation Types' },
+  // Generic org-shared audience taxonomy; membership lives on the contact.
+  { slug: 'contact-groups', name: 'Contact Groups' },
+  // Tone-of-voice synthesis: per-user setups + generated instruction profiles.
+  { slug: 'tone-profiles', name: 'Tone Profiles' },
   // Connectors (connector-service). `connections` above is shared; this is the
   // manifest catalog.
   { slug: 'connectors', name: 'Connectors' },
@@ -80,6 +98,15 @@ export const PLATFORM_ENTITY_SLUGS: readonly string[] = PLATFORM_ENTITIES.map(
   (entity) => entity.slug,
 )
 
+/**
+ * Platform entities whose owning service actually enforces the `*_scoped`
+ * permission verbs (record-level access grants). Granting `read_scoped` on any
+ * other platform entity is legal on the wire but inert — no service narrows
+ * by it — so permission UIs only offer the scoped column for these. Extend as
+ * services adopt scoped enforcement.
+ */
+export const SCOPED_PLATFORM_ENTITY_SLUGS: readonly string[] = ['knowledge-nodes']
+
 /** True when `slug` belongs to a platform entity (reserved; can't be user-created). */
 export function isPlatformEntity(slug: string): boolean {
   return PLATFORM_ENTITY_SLUGS.includes(slug)

package/src/auth/roles.ts

@@ -93,7 +93,9 @@ export interface RoleService {
    * Deletes a role.
    *
    * @param slug - Role slug
-   * @throws {ProteosError} If role not found (404)
+   * @throws {ProteosError} If role not found (404), or if the role still has
+   *   entity permissions attached (400 `role_deletion_not_allowed`) — remove
+   *   the grants first
    */
   delete(slug: string): Promise<void>
 

package/src/auth/shares.ts

@@ -0,0 +1,181 @@
+import type { ProteosClient } from '../client.js'
+import type { PrincipalRef } from '../meta/types.js'
+import { ProteosError } from '../errors.js'
+import type { SharePermission, ShareRequest, ShareRow } from './types.js'
+
+/**
+ * Which service owns each shareable platform entity.
+ *
+ * Sharing is decided by the service that OWNS the resource — whether a caller
+ * may grant depends on what the row itself grants them (its granting
+ * attributes, or an owner column), which only that service can read. So the
+ * write endpoint is per-service by necessity.
+ *
+ * This map is the client-side seam that hides that. Callers name an entity, not
+ * a service, so if sharing is ever centralized behind one endpoint the change is
+ * a one-line edit here and no caller moves.
+ *
+ * Anything NOT listed is a user-defined entity, which data-service owns — that
+ * set is unbounded and appears at runtime, so it is the default rather than an
+ * enumeration.
+ */
+const PLATFORM_ENTITY_SERVICE: Readonly<Record<string, string>> = {
+  // Agent suite (agent-service)
+  agents: '/agents',
+  prompts: '/agents',
+  skills: '/agents',
+  tools: '/agents',
+  toolsets: '/agents',
+  'mcp-servers': '/agents',
+  // Knowledge (knowledge-service)
+  'knowledge-spaces': '/knowledge',
+  'knowledge-nodes': '/knowledge',
+  // Conversations (conversation-service)
+  conversations: '/conversations',
+  connections: '/conversations',
+}
+
+/**
+ * The services that actually serve `/v1/shares` today.
+ *
+ * Deliberately separate from the map above: the other services get the endpoint
+ * in later phases, and until then a share must fail with a clear message rather
+ * than a bare 404 that reads like the record does not exist.
+ */
+const SERVICES_WITH_SHARING: ReadonlySet<string> = new Set(['/data', '/knowledge'])
+
+/** Records live in data-service; user-defined entities are the unlisted majority. */
+const DEFAULT_SERVICE = '/data'
+
+/**
+ * Resolves the share endpoint for an entity slug.
+ *
+ * Exported for tests and for callers that want to check support before offering
+ * a share affordance in a UI.
+ */
+export function shareRouteFor(entitySlug: string): string {
+  const service = PLATFORM_ENTITY_SERVICE[entitySlug] ?? DEFAULT_SERVICE
+  if (!SERVICES_WITH_SHARING.has(service)) {
+    throw new ProteosError(
+      `Sharing is not available for '${entitySlug}' yet — ${service.slice(1)}-service does not serve a share endpoint.`,
+      501,
+      'sharing_not_supported',
+    )
+  }
+  return `${service}/v1/shares`
+}
+
+/** True when `entitySlug` can be shared today. */
+export function isShareable(entitySlug: string): boolean {
+  const service = PLATFORM_ENTITY_SERVICE[entitySlug] ?? DEFAULT_SERVICE
+  return SERVICES_WITH_SHARING.has(service)
+}
+
+/**
+ * Sharing an individual resource with a principal — a person, an agent, an API
+ * client, a team, or the whole organization.
+ *
+ * A share grants access to ONE resource, which is a different thing from a role:
+ * a role grants a permission on an entity TYPE (every deal), a share grants it
+ * on an INSTANCE (this deal). The two compose — a share gives nothing to someone
+ * holding no grant on the entity type at all, which bounds its blast radius to a
+ * population already authorized for that kind of resource.
+ *
+ * Callers name an ENTITY, never a service. Which service handles the write is
+ * this module's problem.
+ *
+ * Who may share: the resource's owner, or someone holding the plain (unscoped)
+ * permission on the entity. Notably NOT a share recipient — access held only
+ * through a share cannot be passed on, and cannot be turned into ownership.
+ */
+export interface ShareService {
+  /**
+   * Grants a principal access to one resource.
+   *
+   * Granting `write` or `delete` implies `read`: a principal who cannot see a
+   * resource must never be able to edit it, so the read is granted alongside.
+   *
+   * @throws {ProteosError} 403 `share_not_permitted` when the caller holds their
+   * own access only through a share; 403 `principal_not_in_org` when the
+   * recipient is outside the caller's organization (rejected outright rather
+   * than written inert, which would become a live grant the moment they joined);
+   * 404 when the resource does not exist or is not visible to the caller;
+   * 501 `sharing_not_supported` when the owning service has no share endpoint.
+   */
+  share(
+    entitySlug: string,
+    recordId: string,
+    principal: PrincipalRef,
+    permission: SharePermission,
+  ): Promise<void>
+
+  /**
+   * Revokes a principal's access to one resource.
+   *
+   * Revoking `read` CASCADES to `write` and `delete` — an edit right on
+   * something someone can no longer see would be incoherent.
+   *
+   * Revocation is deliberately wider than granting: the owner, anyone holding
+   * the unscoped `write` permission, and platform admins may all revoke. Erring
+   * permissive costs nothing here, while erring strict would strand grants
+   * nobody could clean up.
+   */
+  unshare(
+    entitySlug: string,
+    recordId: string,
+    principal: PrincipalRef,
+    permission: SharePermission,
+  ): Promise<void>
+
+  /**
+   * Lists a resource's shares.
+   *
+   * Gated to the population that may REVOKE them — the owner, unscoped-write
+   * holders, and platform admins. Record read is deliberately not enough: a
+   * share list discloses org structure ("this deal is visible to team:legal").
+   *
+   * @throws {ProteosError} 403 `share_listing_not_permitted` otherwise.
+   */
+  listShares(entitySlug: string, recordId: string): Promise<ShareRow[]>
+}
+
+export class ShareServiceImpl implements ShareService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async share(
+    entitySlug: string,
+    recordId: string,
+    principal: PrincipalRef,
+    permission: SharePermission,
+  ): Promise<void> {
+    await this.client.request<void>('POST', shareRouteFor(entitySlug), {
+      entity_slug: entitySlug,
+      record_id: recordId,
+      principal,
+      permission,
+    } satisfies ShareRequest)
+  }
+
+  async unshare(
+    entitySlug: string,
+    recordId: string,
+    principal: PrincipalRef,
+    permission: SharePermission,
+  ): Promise<void> {
+    await this.client.request<void>('DELETE', shareRouteFor(entitySlug), {
+      entity_slug: entitySlug,
+      record_id: recordId,
+      principal,
+      permission,
+    } satisfies ShareRequest)
+  }
+
+  async listShares(entitySlug: string, recordId: string): Promise<ShareRow[]> {
+    const query = new URLSearchParams({ entity_slug: entitySlug, record_id: recordId })
+    const response = await this.client.request<{ shares: ShareRow[] }>(
+      'GET',
+      `${shareRouteFor(entitySlug)}?${query.toString()}`,
+    )
+    return response.shares ?? []
+  }
+}

package/src/auth/teams.ts

@@ -0,0 +1,135 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  AddTeamMemberRequest,
+  CreateTeamRequest,
+  ListTeamMembersOptions,
+  ListTeamsOptions,
+  Team,
+  TeamMember,
+  UpdateTeamRequest,
+} from './types.js'
+
+const TEAMS_BASE_PATH = '/accounts/v1/teams'
+
+/**
+ * Service for managing teams — the org's structure, and a principal that can
+ * hold access anywhere a user can.
+ *
+ * Team 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`. This is the direction people get backwards.
+ */
+export interface TeamService {
+  /**
+   * Lists teams with optional filtering.
+   * Returns an async iterator that automatically handles pagination.
+   */
+  list(options?: ListTeamsOptions): PageIterator<Team, ListTeamsOptions>
+
+  /** Fetches a single page of teams. */
+  listPage(options?: ListTeamsOptions): Promise<ListResult<Team>>
+
+  /**
+   * Gets a single team by slug.
+   * @throws {ProteosError} If the team is not found (404)
+   */
+  get(slug: string): Promise<Team>
+
+  /**
+   * Creates a team, optionally nested under an existing one.
+   * @throws {ProteosError} If the parent would create a cycle or exceed the
+   * maximum depth (400 `team_hierarchy_invalid`)
+   */
+  create(request: CreateTeamRequest): Promise<Team>
+
+  /**
+   * Updates a team's name, description or parent.
+   *
+   * The slug cannot be changed: it is half the primary key and every grant
+   * references `team:<orgId>/<slug>`, so a rename would orphan them. Pass an
+   * empty `parent_team_slug` to promote the team to a root.
+   */
+  update(slug: string, request: UpdateTeamRequest): Promise<Team>
+
+  /**
+   * Deletes a team.
+   * @throws {ProteosError} If the team still has members or child teams
+   * (400 `team_deletion_not_allowed`)
+   */
+  delete(slug: string): Promise<void>
+
+  /**
+   * Lists a team's DIRECT members. Membership of ancestor teams is derived, not
+   * stored, so it does not appear here.
+   */
+  getMembers(
+    slug: string,
+    options?: ListTeamMembersOptions,
+  ): PageIterator<TeamMember, ListTeamMembersOptions>
+
+  /** Adds a user to a team. */
+  addMember(slug: string, request: AddTeamMemberRequest): Promise<TeamMember>
+
+  /** Removes a user from a team. */
+  removeMember(slug: string, userId: string): Promise<void>
+}
+
+/**
+ * Implementation of TeamService.
+ */
+export class TeamServiceImpl implements TeamService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListTeamsOptions = {}): PageIterator<Team, ListTeamsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListTeamsOptions = {}): Promise<ListResult<Team>> {
+    return this.client.requestWithQuery<ListResult<Team>>('GET', TEAMS_BASE_PATH, options)
+  }
+
+  async get(slug: string): Promise<Team> {
+    return this.client.request<Team>('GET', `${TEAMS_BASE_PATH}/${slug}`)
+  }
+
+  async create(request: CreateTeamRequest): Promise<Team> {
+    return this.client.request<Team>('POST', TEAMS_BASE_PATH, request)
+  }
+
+  async update(slug: string, request: UpdateTeamRequest): Promise<Team> {
+    return this.client.request<Team>('PATCH', `${TEAMS_BASE_PATH}/${slug}`, request)
+  }
+
+  async delete(slug: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${TEAMS_BASE_PATH}/${slug}`)
+  }
+
+  getMembers(
+    slug: string,
+    options: ListTeamMembersOptions = {},
+  ): PageIterator<TeamMember, ListTeamMembersOptions> {
+    return new PageIterator((opts) => this.fetchMembersPage(slug, opts), options)
+  }
+
+  async addMember(slug: string, request: AddTeamMemberRequest): Promise<TeamMember> {
+    return this.client.request<TeamMember>('POST', `${TEAMS_BASE_PATH}/${slug}/members`, request)
+  }
+
+  async removeMember(slug: string, userId: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${TEAMS_BASE_PATH}/${slug}/members/${userId}`)
+  }
+
+  private async fetchMembersPage(
+    slug: string,
+    options: ListTeamMembersOptions,
+  ): Promise<ListResult<TeamMember>> {
+    return this.client.requestWithQuery<ListResult<TeamMember>>(
+      'GET',
+      `${TEAMS_BASE_PATH}/${slug}/members`,
+      options,
+    )
+  }
+}