@proteos/sdk 0.18.1

package/src/agent/tools.ts

@@ -0,0 +1,53 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type { CreateToolRequest, ListToolsOptions, Tool, UpdateToolRequest } from './types.js'
+
+const TOOLS_BASE_PATH = '/agents/v1/tools'
+
+/**
+ * Service for managing Tools — thin registry entries over one of three binding
+ * sources (action / mcp / client). `update` fully replaces the definition.
+ */
+export interface ToolService {
+  /** Lists tools, auto-paginating. Filterable by `kind`. */
+  list(options?: ListToolsOptions): PageIterator<Tool, ListToolsOptions>
+  /** Fetches a single page of tools with pagination metadata. */
+  listPage(options?: ListToolsOptions): Promise<ListResult<Tool>>
+  /** Gets a single tool by key. @throws {ProteosError} 404. */
+  get(key: string): Promise<Tool>
+  /** Creates a new tool. @throws {ProteosError} 400/409. */
+  create(request: CreateToolRequest): Promise<Tool>
+  /** Fully replaces a tool's definition. @throws {ProteosError} 404/400. */
+  update(key: string, request: UpdateToolRequest): Promise<Tool>
+  /** Deletes a tool. @throws {ProteosError} 404. */
+  delete(key: string): Promise<void>
+}
+
+export class ToolServiceImpl implements ToolService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListToolsOptions = {}): PageIterator<Tool, ListToolsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListToolsOptions = {}): Promise<ListResult<Tool>> {
+    return this.client.requestWithQuery<ListResult<Tool>>('GET', TOOLS_BASE_PATH, options)
+  }
+
+  async get(key: string): Promise<Tool> {
+    return this.client.request<Tool>('GET', `${TOOLS_BASE_PATH}/${key}`)
+  }
+
+  async create(request: CreateToolRequest): Promise<Tool> {
+    return this.client.request<Tool>('POST', TOOLS_BASE_PATH, request)
+  }
+
+  async update(key: string, request: UpdateToolRequest): Promise<Tool> {
+    return this.client.request<Tool>('PATCH', `${TOOLS_BASE_PATH}/${key}`, request)
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${TOOLS_BASE_PATH}/${key}`)
+  }
+}

package/src/agent/types.ts

@@ -0,0 +1,362 @@
+/**
+ * Types for the Proteos Agent Service API.
+ *
+ * Hand-written mirror of the Go models in `go.proteos.ai/model/agent`
+ * (`agent.go`, `prompt.go`, `skill.go`, `tool.go`, `tool-kind.go`,
+ * `mcp-server.go`, `model-config.go` + `api/*-requests.go`). Field names match
+ * the snake_case wire format exactly, including enum values.
+ *
+ * All five resources are org-scoped and keyed by an immutable kebab-case `key`.
+ */
+
+// `inputs` (prompts) and `input_schema` (tools) reuse the platform attribute
+// shape — the same `Attribute` the meta-service uses for entity attributes and
+// action params. Do not redefine it here.
+import type { Attribute } from '../meta/types.js'
+import type { AuditFields, ListOptions, UserRef } from '../types/common.js'
+
+export type { Attribute } from '../meta/types.js'
+
+/** Shared name/key filter carried by every agent-service list endpoint. */
+export interface AgentResourceListOptions extends ListOptions {
+  /** Exact key match. */
+  key?: string
+  /** Exact name match. */
+  name?: string
+  /** Filter by owning module slug. */
+  module_slug?: string
+  /** Case-insensitive substring match on name. */
+  'name[contains]'?: string
+}
+
+// ---------------------------------------------------------------------------
+// Agents
+// ---------------------------------------------------------------------------
+
+/**
+ * Inline LLM configuration an Agent runs with. v1 carries the model id plus
+ * optional sampling knobs; a provider/credentials registry is deferred.
+ */
+export interface ModelConfig {
+  model_id: string
+  temperature?: number
+  max_tokens?: number
+  thinking?: boolean
+}
+
+/**
+ * A configured persona: a system prompt + model config + the skills, tools,
+ * sub-agents and MCP servers it can use. All references are by key (immutable):
+ * `system_prompt` is a Prompt key; `skills`/`tools`/`subagents`/`mcp_servers` are
+ * Skill/Tool/Agent/McpServer keys. Attaching an MCP server exposes every tool the
+ * server provides (vs a `kind: 'mcp'` tool, which binds a single one). Keyed by
+ * (org_id, key).
+ */
+export interface Agent extends AuditFields {
+  org_id: string
+  key: string
+  name: string
+  module_slug: string
+  description: string
+  system_prompt: string
+  model_config: ModelConfig
+  skills: string[]
+  tools: string[]
+  subagents: string[]
+  mcp_servers: string[]
+  /** Marks the single agent surfaced by default for the org (at most one). */
+  is_org_default: boolean
+  version: number
+}
+
+export interface CreateAgentRequest {
+  key: string
+  name: string
+  module_slug?: string
+  description?: string
+  system_prompt?: string
+  model_config?: ModelConfig
+  skills?: string[]
+  tools?: string[]
+  subagents?: string[]
+  mcp_servers?: string[]
+  is_org_default?: boolean
+}
+
+export interface UpdateAgentRequest {
+  name?: string
+  module_slug?: string
+  description?: string
+  system_prompt?: string
+  model_config?: ModelConfig
+  skills?: string[]
+  tools?: string[]
+  subagents?: string[]
+  mcp_servers?: string[]
+  is_org_default?: boolean
+}
+
+export type ListAgentsOptions = AgentResourceListOptions
+
+// ---------------------------------------------------------------------------
+// Prompts (versioned)
+// ---------------------------------------------------------------------------
+
+/**
+ * An immutable snapshot of a Prompt's content. Editing `body` or `inputs` forks
+ * a new version; metadata-only edits do not. `inputs` declares the Liquid
+ * placeholders the template expects.
+ */
+export interface PromptVersion {
+  id: string
+  number: number
+  org_id: string
+  prompt_key: string
+  body: string
+  inputs: Attribute[]
+  hash: string
+  created_at: string
+  created_by: UserRef
+}
+
+/**
+ * A reusable, Liquid-templated instruction text, versioned like a storage file:
+ * the parent row holds identity + metadata + a pointer to the current immutable
+ * {@link PromptVersion}. Keyed by (org_id, key); key is immutable.
+ */
+export interface Prompt extends AuditFields {
+  org_id: string
+  key: string
+  name: string
+  module_slug: string
+  description: string
+  current_version: PromptVersion | null
+}
+
+export interface CreatePromptRequest {
+  key: string
+  name: string
+  module_slug?: string
+  description?: string
+  body: string
+  inputs?: Attribute[]
+}
+
+/**
+ * A patch: `name`/`description` edit metadata in place; supplying `body` forks a
+ * new immutable version (`inputs` carries forward unless also supplied). A
+ * metadata-only patch creates no version.
+ */
+export interface UpdatePromptRequest {
+  name?: string
+  module_slug?: string
+  description?: string
+  body?: string
+  inputs?: Attribute[]
+}
+
+export type ListPromptsOptions = AgentResourceListOptions
+
+// ---------------------------------------------------------------------------
+// Skills (versioned bundles)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pins the exact immutable storage Version the SKILL.md+files bundle (tar.gz)
+ * was uploaded as. `file_version_id` is the real pin; `checksum_sha256` /
+ * `size_in_bytes` are denormalized for cheap display.
+ */
+export interface SkillBundle {
+  file_id: string
+  file_version_id: string
+  checksum_sha256: string
+  size_in_bytes: number
+}
+
+/** An immutable snapshot pinning one storage bundle. */
+export interface SkillVersion {
+  id: string
+  number: number
+  org_id: string
+  skill_key: string
+  bundle: SkillBundle
+  created_at: string
+  created_by: UserRef
+}
+
+/**
+ * A versioned bundle of instructions + files in the Anthropic Agent-Skills
+ * shape. `key` = the SKILL.md frontmatter `name`. The parent caches the L1
+ * discovery metadata (name + description); the bundle is the source of truth and
+ * lives on the immutable version rows. Created/updated only via the multipart
+ * deploy endpoint, not a JSON body.
+ */
+export interface Skill extends AuditFields {
+  org_id: string
+  key: string
+  name: string
+  module_slug: string
+  description: string
+  current_version: SkillVersion | null
+}
+
+export type ListSkillsOptions = AgentResourceListOptions
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+/**
+ * The binding SOURCE of a Tool: where the callable comes from.
+ * - `action` binds to a function-service Action.
+ * - `mcp` binds to one tool on a registered {@link McpServer}.
+ * - `client` is a host-provided builtin and carries no binding.
+ */
+export type ToolKind = 'action' | 'mcp' | 'client'
+
+/** Binds to a function-service Action by its key (kind=action). */
+export interface ActionBinding {
+  action_key: string
+}
+
+/** Binds to one tool on a registered MCP server (kind=mcp). */
+export interface McpBinding {
+  server_key: string
+  tool_name: string
+}
+
+/** Kind-discriminated binding payload. `kind=client` carries no binding. */
+export type ToolBinding = ActionBinding | McpBinding
+
+/**
+ * A thin registry entry over one of three binding sources. `key` is the wire
+ * name the model calls (`tool_use.name`) and what `Agent.tools` lists.
+ * `input_schema` declares the params. `binding` is decoded by `kind` (absent for
+ * client tools). Keyed by (org_id, key).
+ */
+export interface Tool extends AuditFields {
+  org_id: string
+  key: string
+  name: string
+  module_slug: string
+  description: string
+  kind: ToolKind
+  input_schema: Attribute[]
+  binding?: ToolBinding | null
+  version: number
+}
+
+export interface CreateToolRequest {
+  key: string
+  name: string
+  module_slug?: string
+  description?: string
+  kind: ToolKind
+  input_schema?: Attribute[]
+  /** Omit for `kind=client`. Sent as a structured object; the server decodes it by kind. */
+  binding?: ToolBinding | null
+}
+
+/** Fully replaces the tool's definition (the kind↔binding coupling makes a partial patch ambiguous). */
+export interface UpdateToolRequest {
+  name: string
+  module_slug?: string
+  description?: string
+  kind: ToolKind
+  input_schema?: Attribute[]
+  binding?: ToolBinding | null
+}
+
+export interface ListToolsOptions extends AgentResourceListOptions {
+  /** Filter by binding source. */
+  kind?: ToolKind
+}
+
+// ---------------------------------------------------------------------------
+// MCP Servers
+// ---------------------------------------------------------------------------
+
+/**
+ * Auth config for reaching an MCP server. When `is_secret` is set, the bearer
+ * `token` is secret-managed and redacted to `''` on read. For `type: 'oauth'` the
+ * tokens are held server-side (never on this object); only the durable client
+ * config in `oauth` is persisted.
+ */
+export interface McpServerAuth {
+  type: 'none' | 'bearer' | 'oauth'
+  is_secret: boolean
+  token?: string
+  oauth?: McpServerOAuth
+}
+
+/**
+ * Durable OAuth client config for an MCP server. Leave `client_id`/`client_secret`
+ * blank to attempt Dynamic Client Registration on connect; set them to use a
+ * pre-registered client when the authorization server has no registration endpoint.
+ * The endpoint fields are discovered automatically but may be set manually for an
+ * authorization server that doesn't publish RFC 8414 metadata.
+ */
+export interface McpServerOAuth {
+  client_id?: string
+  client_secret?: string
+  registration_mode?: 'dcr' | 'manual'
+  scopes?: string[]
+  issuer?: string
+  authorization_endpoint?: string
+  token_endpoint?: string
+  registration_endpoint?: string
+  resource?: string
+}
+
+/** One entry of an MCP server's tools/list (the `/tools` subresource). */
+export interface McpToolSummary {
+  name: string
+  title?: string
+  description?: string
+}
+
+export type McpConnectionState = 'disconnected' | 'connected' | 'expired' | 'error'
+
+/** Derived OAuth connection state of an MCP server. */
+export interface McpConnectionStatus {
+  key: string
+  state: McpConnectionState
+  last_connected_at?: string
+  error?: string
+}
+
+/** Returned by {@link McpServerService.startOAuth}: open `authorization_url` in a popup. */
+export interface StartMcpOAuthResponse {
+  authorization_url: string
+  state: string
+}
+
+/**
+ * A registered MCP server an org's agents can call — the source of `kind=mcp`
+ * tools (`McpBinding.server_key` points here). Keyed by (org_id, key).
+ */
+export interface McpServer extends AuditFields {
+  org_id: string
+  key: string
+  name: string
+  module_slug: string
+  url: string
+  auth: McpServerAuth
+}
+
+export interface CreateMcpServerRequest {
+  key: string
+  name: string
+  module_slug?: string
+  url: string
+  auth: McpServerAuth
+}
+
+export interface UpdateMcpServerRequest {
+  name?: string
+  module_slug?: string
+  url?: string
+  auth?: McpServerAuth
+}
+
+export type ListMcpServersOptions = AgentResourceListOptions

package/src/auth/index.ts

@@ -0,0 +1,111 @@
+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 UserService, UserServiceImpl } from './users.js'
+
+/**
+ * Client for the Proteos Auth Service API.
+ * Provides access to all authentication and authorization services.
+ *
+ * @example
+ * ```ts
+ * import { ProteosClient, AccountClient } from 'proteos-sdk';
+ *
+ * const client = new ProteosClient({
+ *   baseUrl: 'https://api.proteos.ai',
+ *   token: 'your-api-token',
+ * });
+ *
+ * const auth = new AccountClient(client);
+ *
+ * // Use services
+ * const users = await auth.users.list().all();
+ * const role = await auth.roles.get('admin');
+ * const org = await auth.organizations.get('org-123');
+ * ```
+ */
+export class AccountClient {
+  /**
+   * Service for caller-scoped queries ("who am I", my organizations).
+   */
+  readonly me: MeService
+
+  /**
+   * Service for managing users and their role assignments.
+   */
+  readonly users: UserService
+
+  /**
+   * Service for managing roles and their entity permissions.
+   */
+  readonly roles: RoleService
+
+  /**
+   * Service for managing organizations.
+   */
+  readonly organizations: OrganizationService
+
+  /**
+   * Creates a new AccountClient instance.
+   *
+   * @param client - The base ProteosClient to use for API requests
+   */
+  constructor(client: ProteosClient) {
+    this.me = new MeServiceImpl(client)
+    this.users = new UserServiceImpl(client)
+    this.roles = new RoleServiceImpl(client)
+    this.organizations = new OrganizationServiceImpl(client)
+  }
+}
+
+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 type { RoleService } from './roles.js'
+// Re-export types
+export type {
+  // Api key types
+  ApiKey,
+  AssignPermissionRequest,
+  AssignRoleRequest,
+  // Shared types
+  AuthListOptions,
+  CreateApiKeyRequest,
+  CreatedApiKey,
+  CreateOrganizationRequest,
+  CreateRoleRequest,
+  CreateUserRequest,
+  ListOrganizationsOptions,
+  ListRolePermissionsOptions,
+  ListRolesOptions,
+  ListUserRoleAssignmentsOptions,
+  ListUsersOptions,
+  // Organization types
+  Organization,
+  // Permission types
+  Permission,
+  // Role types
+  Role,
+  RoleEntityPermission,
+  UpdateOrganizationRequest,
+  UpdateRoleRequest,
+  UpdateUserRequest,
+  // User types
+  User,
+  // User role assignment types
+  UserRoleAssignment,
+} from './types.js'
+// Re-export Zod schemas
+export {
+  ApiKeySchema,
+  OrganizationSchema,
+  RoleEntityPermissionSchema,
+  RoleSchema,
+  UserRoleAssignmentSchema,
+  UserSchema,
+} from './types.js'
+// Re-export service interfaces
+export type { UserService } from './users.js'

package/src/auth/me.ts

@@ -0,0 +1,46 @@
+import type { ProteosClient } from '../client.js'
+import type { Organization, User } from './types.js'
+
+const ME_BASE_PATH = '/accounts/v1/me'
+
+/**
+ * Service for caller-scoped queries — answers about the authenticated user
+ * (from the token), not an arbitrary user id.
+ */
+export interface MeService {
+  /**
+   * Gets the caller's own user record, resolved from the token's user id.
+   * The canonical "who am I" — use this instead of filtering `users.list`
+   * by email.
+   *
+   * @returns The calling user
+   */
+  get(): 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.
+   *
+   * @returns The caller's organizations
+   */
+  organizations(): Promise<Organization[]>
+}
+
+/**
+ * Implementation of MeService.
+ */
+export class MeServiceImpl implements MeService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async get(): Promise<User> {
+    return this.client.request<User>('GET', ME_BASE_PATH)
+  }
+
+  async organizations(): Promise<Organization[]> {
+    const response = await this.client.request<{ data: Organization[] }>(
+      'GET',
+      `${ME_BASE_PATH}/organizations`,
+    )
+    return response.data
+  }
+}

package/src/auth/organizations.ts

@@ -0,0 +1,128 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateOrganizationRequest,
+  ListOrganizationsOptions,
+  Organization,
+  UpdateOrganizationRequest,
+} from './types.js'
+
+const ORGANIZATIONS_BASE_PATH = '/accounts/v1/organizations'
+
+/**
+ * Service for managing organizations.
+ * Handles organization CRUD operations.
+ */
+export interface OrganizationService {
+  /**
+   * Lists organizations with optional filtering.
+   * Returns an async iterator that automatically handles pagination.
+   *
+   * @param options - Filter and pagination options
+   * @returns Async iterator over organizations
+   *
+   * @example
+   * ```ts
+   * // Iterate over all organizations
+   * for await (const org of service.list()) {
+   *   console.log(org.name);
+   * }
+   *
+   * // With filtering
+   * for await (const org of service.list({ name: 'Acme Corp' })) {
+   *   console.log(org.id);
+   * }
+   * ```
+   */
+  list(options?: ListOrganizationsOptions): PageIterator<Organization, ListOrganizationsOptions>
+
+  /**
+   * Fetches a single page of organizations.
+   *
+   * @param options - Filter and pagination options (including `page`)
+   * @returns A single page of organizations with pagination metadata
+   */
+  listPage(options?: ListOrganizationsOptions): Promise<ListResult<Organization>>
+
+  /**
+   * Gets a single organization by ID.
+   *
+   * @param id - Organization ID
+   * @returns The organization
+   * @throws {ProteosError} If organization not found (404)
+   */
+  get(id: string): Promise<Organization>
+
+  /**
+   * Creates a new organization.
+   *
+   * @param request - Organization creation request
+   * @returns The created organization
+   * @throws {ProteosError} If validation fails (400) or conflict (409)
+   *
+   * @example
+   * ```ts
+   * const org = await service.create({
+   *   name: 'Acme Corporation',
+   *   description: 'Main organization',
+   * });
+   * ```
+   */
+  create(request: CreateOrganizationRequest): Promise<Organization>
+
+  /**
+   * Updates an existing organization.
+   *
+   * @param id - Organization ID
+   * @param request - Fields to update
+   * @returns The updated organization
+   * @throws {ProteosError} If organization not found (404) or validation fails (400)
+   */
+  update(id: string, request: UpdateOrganizationRequest): Promise<Organization>
+
+  /**
+   * Deletes an organization.
+   *
+   * @param id - Organization ID
+   * @throws {ProteosError} If organization not found (404)
+   */
+  delete(id: string): Promise<void>
+}
+
+/**
+ * Implementation of OrganizationService.
+ */
+export class OrganizationServiceImpl implements OrganizationService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    options: ListOrganizationsOptions = {},
+  ): PageIterator<Organization, ListOrganizationsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListOrganizationsOptions = {}): Promise<ListResult<Organization>> {
+    return this.client.requestWithQuery<ListResult<Organization>>(
+      'GET',
+      ORGANIZATIONS_BASE_PATH,
+      options,
+    )
+  }
+
+  async get(id: string): Promise<Organization> {
+    return this.client.request<Organization>('GET', `${ORGANIZATIONS_BASE_PATH}/${id}`)
+  }
+
+  async create(request: CreateOrganizationRequest): Promise<Organization> {
+    return this.client.request<Organization>('POST', ORGANIZATIONS_BASE_PATH, request)
+  }
+
+  async update(id: string, request: UpdateOrganizationRequest): Promise<Organization> {
+    return this.client.request<Organization>('PATCH', `${ORGANIZATIONS_BASE_PATH}/${id}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${ORGANIZATIONS_BASE_PATH}/${id}`)
+  }
+}