@proteos/sdk 0.18.1

package/src/auth/platform-entities.ts

@@ -0,0 +1,78 @@
+/**
+ * Canonical platform entities — the built-in system resources (users, roles,
+ * files, entities, …) that are permission targets alongside user-defined
+ * entities. Hand-maintained mirror of the Go registry in
+ * packages/go/model/platform/entities.go — keep the two in sync.
+ *
+ * Used by the role-permission UI to list grantable platform entities next to
+ * user-defined entities (from `meta.entities.list()`); permissions key on a
+ * free-form `entity_slug`, so the two are assigned uniformly.
+ */
+export interface PlatformEntity {
+  slug: string
+  /** Display label for the role-permission dropdown. */
+  name: string
+}
+
+/** The canonical platform entities, in display order. */
+export const PLATFORM_ENTITIES: readonly PlatformEntity[] = [
+  // Access (account-service)
+  { slug: 'organizations', name: 'Organizations' },
+  { slug: 'users', name: 'Users' },
+  { slug: 'roles', name: 'Roles' },
+  { slug: 'user-role-assignments', name: 'User Role Assignments' },
+  { slug: 'role-entity-permissions', name: 'Role Entity Permissions' },
+  // Schema / content (metadata-service)
+  { slug: 'entities', name: 'Entities' },
+  { slug: 'pages', name: 'Pages' },
+  { slug: 'menu-configurations', name: 'Menu Configurations' },
+  { slug: 'apps', name: 'Apps' },
+  { slug: 'components', name: 'Components' },
+  { slug: 'lists', name: 'Lists' },
+  { slug: 'list-views', name: 'List Views' },
+  // System (metadata-service)
+  { slug: 'modules', name: 'Modules' },
+  { slug: 'variables', name: 'Variables' },
+  { slug: 'deployments', name: 'Deployments' },
+  // Storage (storage-service)
+  { slug: 'files', name: 'Files' },
+  // Automation (function-service)
+  { slug: 'hooks', name: 'Hooks' },
+  { slug: 'actions', name: 'Actions' },
+  // Knowledge (knowledge-service)
+  { slug: 'knowledge-nodes', name: 'Knowledge Nodes' },
+  { slug: 'knowledge-links', name: 'Knowledge Links' },
+  { slug: 'knowledge-labels', name: 'Knowledge Labels' },
+  // Agent suite (agent-service)
+  { slug: 'agents', name: 'Agents' },
+  { slug: 'prompts', name: 'Prompts' },
+  { slug: 'skills', name: 'Skills' },
+  { slug: 'tools', name: 'Tools' },
+  { slug: 'mcp-servers', name: 'MCP Servers' },
+  { slug: 'agent-sessions', name: 'Agent Sessions' },
+  // Messaging bus (event-service)
+  { slug: 'topics', name: 'Topics' },
+  { slug: 'events', name: 'Events' },
+  // Conversations (conversation-service). NOTE: `connections` is enforced by
+  // BOTH conversation-service and connector-service (2026-07 decision) — same
+  // concept in both; conversation connections migrate onto connector-service
+  // later.
+  { slug: 'connections', name: 'Connections' },
+  { slug: 'conversations', name: 'Conversations' },
+  { slug: 'messages', name: 'Messages' },
+  { slug: 'agent-listeners', name: 'Agent Listeners' },
+  { slug: 'transcriptions', name: 'Transcriptions' },
+  // Connectors (connector-service). `connections` above is shared; this is the
+  // manifest catalog.
+  { slug: 'connectors', name: 'Connectors' },
+] as const
+
+/** Just the platform entity slugs, in canonical order. */
+export const PLATFORM_ENTITY_SLUGS: readonly string[] = PLATFORM_ENTITIES.map(
+  (entity) => entity.slug,
+)
+
+/** 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

@@ -0,0 +1,213 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  AssignPermissionRequest,
+  CreateRoleRequest,
+  ListRolePermissionsOptions,
+  ListRolesOptions,
+  Role,
+  RoleEntityPermission,
+  UpdateRoleRequest,
+} from './types.js'
+
+const ROLES_BASE_PATH = '/accounts/v1/roles'
+
+/**
+ * Service for managing roles.
+ * Handles role CRUD operations and permission assignments.
+ */
+export interface RoleService {
+  /**
+   * Lists roles with optional filtering.
+   * Returns an async iterator that automatically handles pagination.
+   *
+   * @param options - Filter and pagination options
+   * @returns Async iterator over roles
+   *
+   * @example
+   * ```ts
+   * // Iterate over all roles
+   * for await (const role of service.list()) {
+   *   console.log(role.name);
+   * }
+   *
+   * // With filtering
+   * for await (const role of service.list({ org_id: 'org-123' })) {
+   *   console.log(role.slug);
+   * }
+   * ```
+   */
+  list(options?: ListRolesOptions): PageIterator<Role, ListRolesOptions>
+
+  /**
+   * Gets a single role by slug.
+   *
+   * @param slug - Role slug
+   * @returns The role
+   * @throws {ProteosError} If role not found (404)
+   */
+  get(slug: string): Promise<Role>
+
+  /**
+   * Creates a new role.
+   *
+   * @param request - Role creation request
+   * @returns The created role
+   * @throws {ProteosError} If validation fails (400) or conflict (409)
+   *
+   * @example
+   * ```ts
+   * const role = await service.create({
+   *   org_id: 'org-123',
+   *   slug: 'admin',
+   *   name: 'Administrator',
+   *   description: 'Full system access',
+   * });
+   * ```
+   */
+  create(request: CreateRoleRequest): Promise<Role>
+
+  /**
+   * Creates or updates a role idempotently by slug. The URL slug wins on
+   * mismatch with the body's slug field (`PUT /accounts/v1/roles/:slug`). The
+   * org is taken from the caller's token, not the body.
+   *
+   * @param slug - Role slug
+   * @param request - Full role body
+   * @returns The created or updated role
+   */
+  upsert(slug: string, request: CreateRoleRequest): Promise<Role>
+
+  /**
+   * Updates an existing role.
+   *
+   * @param slug - Role slug
+   * @param request - Fields to update
+   * @returns The updated role
+   * @throws {ProteosError} If role not found (404) or validation fails (400)
+   */
+  update(slug: string, request: UpdateRoleRequest): Promise<Role>
+
+  /**
+   * Deletes a role.
+   *
+   * @param slug - Role slug
+   * @throws {ProteosError} If role not found (404)
+   */
+  delete(slug: string): Promise<void>
+
+  /**
+   * Fetches a single page of roles.
+   *
+   * @param options - Filter and pagination options (including `page`)
+   * @returns A single page of roles with pagination metadata
+   */
+  listPage(options?: ListRolesOptions): Promise<ListResult<Role>>
+
+  /**
+   * Gets permissions assigned to a role.
+   * Returns an async iterator that automatically handles pagination.
+   *
+   * @param roleSlug - Role slug
+   * @param options - Filter and pagination options
+   * @returns Async iterator over role entity permissions
+   */
+  getPermissions(
+    roleSlug: string,
+    options?: ListRolePermissionsOptions,
+  ): PageIterator<RoleEntityPermission, ListRolePermissionsOptions>
+
+  /**
+   * Assigns a permission to a role for an entity.
+   *
+   * @param roleSlug - Role slug
+   * @param request - Permission assignment request
+   * @returns The created role entity permission
+   * @throws {ProteosError} If role or entity not found (404)
+   */
+  assignPermission(
+    roleSlug: string,
+    request: AssignPermissionRequest,
+  ): Promise<RoleEntityPermission>
+
+  /**
+   * Removes a permission from a role.
+   *
+   * @param roleSlug - Role slug
+   * @param permissionId - Permission ID to remove
+   * @throws {ProteosError} If permission not found (404)
+   */
+  removePermission(roleSlug: string, permissionId: string): Promise<void>
+}
+
+/**
+ * Implementation of RoleService.
+ */
+export class RoleServiceImpl implements RoleService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListRolesOptions = {}): PageIterator<Role, ListRolesOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListRolesOptions = {}): Promise<ListResult<Role>> {
+    return this.client.requestWithQuery<ListResult<Role>>('GET', ROLES_BASE_PATH, options)
+  }
+
+  async get(slug: string): Promise<Role> {
+    return this.client.request<Role>('GET', `${ROLES_BASE_PATH}/${slug}`)
+  }
+
+  async create(request: CreateRoleRequest): Promise<Role> {
+    return this.client.request<Role>('POST', ROLES_BASE_PATH, request)
+  }
+
+  async upsert(slug: string, request: CreateRoleRequest): Promise<Role> {
+    return this.client.request<Role>('PUT', `${ROLES_BASE_PATH}/${slug}`, { ...request, slug })
+  }
+
+  async update(slug: string, request: UpdateRoleRequest): Promise<Role> {
+    return this.client.request<Role>('PATCH', `${ROLES_BASE_PATH}/${slug}`, request)
+  }
+
+  async delete(slug: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${ROLES_BASE_PATH}/${slug}`)
+  }
+
+  getPermissions(
+    roleSlug: string,
+    options: ListRolePermissionsOptions = {},
+  ): PageIterator<RoleEntityPermission, ListRolePermissionsOptions> {
+    return new PageIterator((opts) => this.fetchPermissionsPage(roleSlug, opts), options)
+  }
+
+  async assignPermission(
+    roleSlug: string,
+    request: AssignPermissionRequest,
+  ): Promise<RoleEntityPermission> {
+    return this.client.request<RoleEntityPermission>(
+      'POST',
+      `${ROLES_BASE_PATH}/${roleSlug}/permissions`,
+      request,
+    )
+  }
+
+  async removePermission(roleSlug: string, permissionId: string): Promise<void> {
+    await this.client.request<void>(
+      'DELETE',
+      `${ROLES_BASE_PATH}/${roleSlug}/permissions/${permissionId}`,
+    )
+  }
+
+  private async fetchPermissionsPage(
+    roleSlug: string,
+    options: ListRolePermissionsOptions,
+  ): Promise<ListResult<RoleEntityPermission>> {
+    return this.client.requestWithQuery<ListResult<RoleEntityPermission>>(
+      'GET',
+      `${ROLES_BASE_PATH}/${roleSlug}/permissions`,
+      options,
+    )
+  }
+}

package/src/auth/types.ts

@@ -0,0 +1,294 @@
+import { z } from 'zod'
+import type { AuditFields, ListOptions } from '../types/common.js'
+import { AuditFieldsSchema } from '../types/common.js'
+
+// ============================================================================
+// Shared Auth Types
+// ============================================================================
+
+/**
+ * Base list options with source filters for the auth namespace.
+ */
+export interface AuthListOptions extends ListOptions {
+  created_by?: string
+  updated_by?: string
+}
+
+// ============================================================================
+// Permission Types
+// ============================================================================
+
+/**
+ * Permission level for entity access.
+ */
+export type Permission = 'read' | 'write' | 'delete'
+
+/**
+ * Role entity permission - permission granted to a role for a specific entity.
+ */
+export interface RoleEntityPermission extends AuditFields {
+  id: string
+  org_id: string
+  role_slug: string
+  entity_slug: string
+  permission: Permission
+}
+
+export const RoleEntityPermissionSchema = AuditFieldsSchema.extend({
+  id: z.string(),
+  role_slug: z.string(),
+  entity_slug: z.string(),
+  permission: z.enum(['read', 'write', 'delete']),
+})
+
+/**
+ * Request to assign a permission to a role.
+ */
+export interface AssignPermissionRequest {
+  entity_slug: string
+  permission: Permission
+}
+
+/**
+ * Options for listing role permissions.
+ */
+export interface ListRolePermissionsOptions extends AuthListOptions {
+  id?: string
+  entity_slug?: string
+  permission?: Permission
+}
+
+// ============================================================================
+// User Role Assignment Types
+// ============================================================================
+
+/**
+ * User role assignment - a role assigned to a user.
+ */
+export interface UserRoleAssignment extends AuditFields {
+  id: string
+  user_id: string
+  role_slug: string
+  org_id: string
+}
+
+export const UserRoleAssignmentSchema = AuditFieldsSchema.extend({
+  id: z.string(),
+  user_id: z.string(),
+  role_slug: z.string(),
+  org_id: z.string(),
+})
+
+/**
+ * Request to assign a role to a user.
+ */
+export interface AssignRoleRequest {
+  role_slug: string
+}
+
+/**
+ * Options for listing user role assignments.
+ */
+export interface ListUserRoleAssignmentsOptions extends AuthListOptions {
+  id?: string
+  role_slug?: string
+}
+
+// ============================================================================
+// User Types
+// ============================================================================
+
+/**
+ * User in the system.
+ */
+export interface User extends AuditFields {
+  id: string
+  email: string
+  given_name: string
+  family_name: string
+  external_id: string
+  default_org_id: string
+}
+
+export const UserSchema = AuditFieldsSchema.extend({
+  id: z.string(),
+  email: z.string(),
+  given_name: z.string(),
+  family_name: z.string(),
+  external_id: z.string(),
+  default_org_id: z.string(),
+})
+
+/**
+ * Request to create a user.
+ */
+export interface CreateUserRequest {
+  given_name: string
+  family_name: string
+  email: string
+  default_org_id?: string
+}
+
+/**
+ * Request to update a user.
+ */
+export interface UpdateUserRequest {
+  given_name?: string
+  family_name?: string
+  default_org_id?: string
+}
+
+/**
+ * Options for listing users.
+ */
+export interface ListUsersOptions extends AuthListOptions {
+  id?: string
+  given_name?: string
+  family_name?: string
+  email?: string
+  default_org_id?: string
+}
+
+// ============================================================================
+// Api Key Types
+// ============================================================================
+
+/**
+ * A user-scoped API key (pak_ token). Only the display hints
+ * (token_prefix/token_suffix) are readable after creation — the full token
+ * appears exactly once in {@link CreatedApiKey}.
+ */
+export interface ApiKey extends AuditFields {
+  id: string
+  user_id: string
+  org_id: string
+  name: string
+  token_prefix: string
+  token_suffix: string
+  /** ISO timestamp; null = the key never expires. */
+  expires_at: string | null
+  last_used_at: string | null
+}
+
+export const ApiKeySchema = AuditFieldsSchema.extend({
+  id: z.string(),
+  user_id: z.string(),
+  org_id: z.string(),
+  name: z.string(),
+  token_prefix: z.string(),
+  token_suffix: z.string(),
+  expires_at: z.string().nullable(),
+  last_used_at: z.string().nullable(),
+})
+
+/**
+ * Create response: the key plus the full token, returned exactly once.
+ * Store it immediately — it is not retrievable afterwards.
+ */
+export interface CreatedApiKey extends ApiKey {
+  token: string
+}
+
+/**
+ * Request to create an API key. Omitting expires_at creates a key that never
+ * expires; omitting org_id binds the key to the user's default org.
+ */
+export interface CreateApiKeyRequest {
+  name: string
+  org_id?: string
+  expires_at?: string
+}
+
+// ============================================================================
+// Role Types
+// ============================================================================
+
+/**
+ * Role in the system.
+ */
+export interface Role extends AuditFields {
+  slug: string
+  name: string
+  org_id: string
+  description: string
+}
+
+export const RoleSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  name: z.string(),
+  org_id: z.string(),
+  description: z.string(),
+})
+
+/**
+ * Request to create a role.
+ */
+export interface CreateRoleRequest {
+  org_id: string
+  slug: string
+  name: string
+  description?: string
+}
+
+/**
+ * Request to update a role.
+ */
+export interface UpdateRoleRequest {
+  org_id?: string
+  name?: string
+  description?: string
+}
+
+/**
+ * Options for listing roles.
+ */
+export interface ListRolesOptions extends AuthListOptions {
+  org_id?: string
+  slug?: string
+  name?: string
+  description?: string
+}
+
+// ============================================================================
+// Organization Types
+// ============================================================================
+
+/**
+ * Organization in the system.
+ */
+export interface Organization extends AuditFields {
+  id: string
+  name: string
+  description: string
+}
+
+export const OrganizationSchema = AuditFieldsSchema.extend({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+})
+
+/**
+ * Request to create an organization.
+ */
+export interface CreateOrganizationRequest {
+  name: string
+  description?: string
+}
+
+/**
+ * Request to update an organization.
+ */
+export interface UpdateOrganizationRequest {
+  name?: string
+  description?: string
+}
+
+/**
+ * Options for listing organizations.
+ */
+export interface ListOrganizationsOptions extends AuthListOptions {
+  id?: string
+  name?: string
+  description?: string
+}