@proteos/sdk 0.18.1

package/src/connector/index.ts

@@ -0,0 +1,120 @@
+import type { ProteosClient } from '../client.js'
+import type {
+  Connector,
+  ConnectorConnection,
+  ConnectorMethod,
+  ConnectionTokenResponse,
+  CreateConnectorConnectionRequest,
+  InstallConnectorConnectionResponse,
+  InvokeMethodResponse,
+  ListConnectorConnectionsQuery,
+  ListConnectorsQuery,
+  ListResponse,
+  UpdateConnectorConnectionRequest,
+} from './types.js'
+
+export * from './types.js'
+
+const CONNECTOR_BASE_PATH = '/connectors/v1'
+
+/**
+ * Facade for connector-service: the connector manifest catalog and
+ * connections (install flow, token release, connector-method invocation).
+ *
+ * ```ts
+ * const connector = new ConnectorClient(client)
+ * const catalog = await connector.connectors.list()
+ * const { authorization_url } = await connector.connections.install(id)
+ * const events = await connector.connections.invokeMethod(id, 'list_events', {})
+ * ```
+ */
+export class ConnectorClient {
+  readonly connectors: ConnectorCatalogService
+  readonly connections: ConnectorConnectionService
+
+  constructor(client: ProteosClient) {
+    this.connectors = new ConnectorCatalogServiceImpl(client)
+    this.connections = new ConnectorConnectionServiceImpl(client)
+  }
+}
+
+/** The connector manifest catalog (pre-built + org-custom). */
+export interface ConnectorCatalogService {
+  list(query?: ListConnectorsQuery): Promise<ListResponse<Connector>>
+  get(key: string): Promise<Connector>
+  /** A connector's callable methods (sugar over get().methods). */
+  listMethods(key: string): Promise<ConnectorMethod[]>
+}
+
+class ConnectorCatalogServiceImpl implements ConnectorCatalogService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListConnectorsQuery = {}): Promise<ListResponse<Connector>> {
+    return this.client.requestWithQuery('GET', `${CONNECTOR_BASE_PATH}/connectors`, query)
+  }
+
+  get(key: string): Promise<Connector> {
+    return this.client.request('GET', `${CONNECTOR_BASE_PATH}/connectors/${encodeURIComponent(key)}`)
+  }
+
+  async listMethods(key: string): Promise<ConnectorMethod[]> {
+    const connector = await this.get(key)
+    return connector.methods ?? []
+  }
+}
+
+/** Configured integration instances + method invocation. */
+export interface ConnectorConnectionService {
+  list(query?: ListConnectorConnectionsQuery): Promise<ListResponse<ConnectorConnection>>
+  get(id: string): Promise<ConnectorConnection>
+  create(request: CreateConnectorConnectionRequest): Promise<ConnectorConnection>
+  update(id: string, request: UpdateConnectorConnectionRequest): Promise<ConnectorConnection>
+  delete(id: string): Promise<void>
+  /** Begin the OAuth install flow; open the returned URL in a popup. */
+  install(id: string): Promise<InstallConnectorConnectionResponse>
+  /** Release the connection's usable token material (requires connections write). */
+  token(id: string): Promise<ConnectionTokenResponse>
+  /** Invoke a connector method; returns the unwrapped result. */
+  invokeMethod<T = unknown>(id: string, method: string, params?: unknown): Promise<T>
+}
+
+class ConnectorConnectionServiceImpl implements ConnectorConnectionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListConnectorConnectionsQuery = {}): Promise<ListResponse<ConnectorConnection>> {
+    return this.client.requestWithQuery('GET', `${CONNECTOR_BASE_PATH}/connections`, query)
+  }
+
+  get(id: string): Promise<ConnectorConnection> {
+    return this.client.request('GET', `${CONNECTOR_BASE_PATH}/connections/${encodeURIComponent(id)}`)
+  }
+
+  create(request: CreateConnectorConnectionRequest): Promise<ConnectorConnection> {
+    return this.client.request('POST', `${CONNECTOR_BASE_PATH}/connections`, request)
+  }
+
+  update(id: string, request: UpdateConnectorConnectionRequest): Promise<ConnectorConnection> {
+    return this.client.request('PATCH', `${CONNECTOR_BASE_PATH}/connections/${encodeURIComponent(id)}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request('DELETE', `${CONNECTOR_BASE_PATH}/connections/${encodeURIComponent(id)}`)
+  }
+
+  install(id: string): Promise<InstallConnectorConnectionResponse> {
+    return this.client.request('POST', `${CONNECTOR_BASE_PATH}/connections/${encodeURIComponent(id)}/install`)
+  }
+
+  token(id: string): Promise<ConnectionTokenResponse> {
+    return this.client.request('POST', `${CONNECTOR_BASE_PATH}/connections/${encodeURIComponent(id)}/token`)
+  }
+
+  async invokeMethod<T = unknown>(id: string, method: string, params: unknown = {}): Promise<T> {
+    const response = await this.client.request<InvokeMethodResponse<T>>(
+      'POST',
+      `${CONNECTOR_BASE_PATH}/connections/${encodeURIComponent(id)}/methods/${encodeURIComponent(method)}/invoke`,
+      params,
+    )
+    return response.result
+  }
+}

package/src/connector/types.ts

@@ -0,0 +1,150 @@
+import type { Attribute } from '../meta/types.js'
+
+/** Connection lifecycle status. */
+export type ConnectionStatus = 'pending' | 'active' | 'error' | 'revoked'
+
+/** org-wide integration vs a single user's grant. */
+export type ConnectionScope = 'org' | 'user'
+
+/** How a connector authenticates. */
+export type CredentialKind = 'oauth' | 'api_key' | 'basic' | 'bot_token'
+
+export interface UserRef {
+  type: string
+  id: string
+}
+
+/**
+ * One callable operation a connector exposes (get_event, update_event, …).
+ * Params/Returns use the platform attribute language — the same shape actions
+ * use — so pickers and validation work identically for pre-built and custom
+ * connectors.
+ */
+export interface ConnectorMethod {
+  key: string
+  title: string
+  description?: string
+  access: 'read' | 'write'
+  /** function-service action implementing this method (custom connectors only). */
+  action_slug?: string
+  params: Attribute[]
+  returns: Attribute[]
+}
+
+/**
+ * The provider config of an oauth connector. Carries no secrets — the OAuth
+ * APP credentials are org VARIABLES referenced by the two *_variable_key
+ * fields (app credentials are variables, tokens are connections).
+ */
+export interface ConnectorOAuthConfig {
+  auth_url: string
+  token_url: string
+  scopes: string[]
+  is_pkce_enabled?: boolean
+  client_id_variable_key: string
+  client_secret_variable_key: string
+}
+
+/** A connector TYPE (google-calendar, a customer's vertex-tax, …). */
+export interface Connector {
+  key: string
+  org_id: string
+  title: string
+  description?: string
+  icon?: string
+  credential_kind: CredentialKind
+  oauth?: ConnectorOAuthConfig
+  /**
+   * COMPUTED: the broker's per-environment OAuth callback — register it as an
+   * authorized redirect URI on the provider app.
+   */
+  oauth_redirect_uri?: string
+  config_schema?: Attribute[]
+  methods: ConnectorMethod[]
+  origin: 'pre_built' | 'custom'
+  module_slug?: string
+  status: 'active' | 'inactive'
+}
+
+/**
+ * One configured integration instance. `Connection` collides with the
+ * conversation module's export, so connector types are prefixed
+ * `ConnectorConnection`.
+ */
+export interface ConnectorConnection {
+  id: string
+  org_id: string
+  connector_key: string
+  display_name: string
+  scope: ConnectionScope
+  owner?: UserRef
+  external_account_id: string
+  settings: Record<string, unknown>
+  status: ConnectionStatus
+  status_detail?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface WriteCredentialsRequest {
+  kind: CredentialKind
+  api_key?: string
+  username?: string
+  password?: string
+  bot_token?: string
+}
+
+export interface CreateConnectorConnectionRequest {
+  connector_key: string
+  display_name: string
+  scope: ConnectionScope
+  settings?: Record<string, unknown>
+  credentials?: WriteCredentialsRequest
+}
+
+export interface UpdateConnectorConnectionRequest {
+  display_name?: string
+  settings?: Record<string, unknown>
+  credentials?: WriteCredentialsRequest
+}
+
+export interface InstallConnectorConnectionResponse {
+  authorization_url: string
+}
+
+export interface ConnectionTokenResponse {
+  kind: CredentialKind
+  access_token?: string
+  expires_at?: string
+  api_key?: string
+  username?: string
+  password?: string
+  bot_token?: string
+}
+
+export interface InvokeMethodResponse<T = unknown> {
+  result: T
+}
+
+export interface ListConnectorsQuery {
+  page?: number
+  page_size?: number
+  status?: string
+}
+
+export interface ListConnectorConnectionsQuery {
+  page?: number
+  page_size?: number
+  connector_key?: string
+  scope?: ConnectionScope
+  status?: ConnectionStatus
+}
+
+export interface ListResponse<T> {
+  data: T[]
+  meta: {
+    pagination: { page: number; page_size: number }
+    items_total: number
+    pages_total: number
+  }
+}

package/src/conversation/index.ts

@@ -0,0 +1,297 @@
+import type { ProteosClient } from '../client.js'
+import { type VoiceService, VoiceServiceImpl } from './voice.js'
+import type {
+  AgentListener,
+  CreateTranscriptionRequest,
+  ListTranscriptionsQuery,
+  MaterializeTranscriptionRequest,
+  Transcription,
+  Connection,
+  Conversation,
+  CreateAgentListenerRequest,
+  CreateConnectionRequest,
+  InstallConnectionResponse,
+  ListAgentListenersQuery,
+  ListConnectionsQuery,
+  ListConversationsQuery,
+  ListMessagesQuery,
+  ListParticipantsQuery,
+  ListReactionsResponse,
+  ListResponse,
+  ListRoomsQuery,
+  Message,
+  Participant,
+  Reaction,
+  Room,
+  SendMessageRequest,
+  UnreadCounts,
+  UpdateAgentListenerRequest,
+  UpdateConnectionRequest,
+} from './types.js'
+
+const CONVERSATION_BASE_PATH = '/conversations/v1'
+
+/**
+ * Facade for conversation-service: connections (channel-connector instances),
+ * conversations + messages (THE platform Message), and agent listeners.
+ *
+ * ```ts
+ * const conversation = new ConversationClient(client)
+ * const { authorization_url } = await conversation.connections.install(id)
+ * const inbox = await conversation.conversations.list({ channel: 'slack' })
+ * ```
+ */
+export class ConversationClient {
+  readonly connections: ConnectionService
+  readonly conversations: ConversationService
+  readonly messages: MessageService
+  readonly agentListeners: AgentListenerService
+  readonly transcriptions: TranscriptionService
+  /** Realtime speech-to-text (dictation) — moved here from agent-service. */
+  readonly voice: VoiceService
+
+  constructor(client: ProteosClient) {
+    this.connections = new ConnectionServiceImpl(client)
+    this.conversations = new ConversationServiceImpl(client)
+    this.messages = new MessageServiceImpl(client)
+    this.agentListeners = new AgentListenerServiceImpl(client)
+    this.transcriptions = new TranscriptionServiceImpl(client)
+    this.voice = new VoiceServiceImpl(client)
+  }
+}
+
+/** Configured integration instances (Slack workspace, Gmail grant, …). */
+export interface ConnectionService {
+  list(query?: ListConnectionsQuery): Promise<ListResponse<Connection>>
+  get(id: string): Promise<Connection>
+  create(request: CreateConnectionRequest): Promise<Connection>
+  update(id: string, request: UpdateConnectionRequest): Promise<Connection>
+  delete(id: string): Promise<void>
+  /** Begin the connector's install flow; open the returned URL in a popup. */
+  install(id: string): Promise<InstallConnectionResponse>
+  /** Search a connection's known PEOPLE (workspace members, correspondents) for the compose picker. */
+  listParticipants(connectionId: string, query?: ListParticipantsQuery): Promise<ListResponse<Participant>>
+  /** Search a connection's addressable VENUES (Slack channels) for the compose picker. */
+  listRooms(connectionId: string, query?: ListRoomsQuery): Promise<ListResponse<Room>>
+}
+
+class ConnectionServiceImpl implements ConnectionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListConnectionsQuery = {}): Promise<ListResponse<Connection>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/connections`, query)
+  }
+
+  get(id: string): Promise<Connection> {
+    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`)
+  }
+
+  create(request: CreateConnectionRequest): Promise<Connection> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/connections`, request)
+  }
+
+  update(id: string, request: UpdateConnectionRequest): Promise<Connection> {
+    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}`)
+  }
+
+  install(id: string): Promise<InstallConnectionResponse> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}/install`)
+  }
+
+  listParticipants(connectionId: string, query: ListParticipantsQuery = {}): Promise<ListResponse<Participant>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/participants`,
+      query,
+    )
+  }
+
+  listRooms(connectionId: string, query: ListRoomsQuery = {}): Promise<ListResponse<Room>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(connectionId)}/rooms`,
+      query,
+    )
+  }
+}
+
+/** Conversation threads across every channel (inbox order: last_message_at). */
+export interface ConversationService {
+  list(query?: ListConversationsQuery): Promise<ListResponse<Conversation>>
+  get(id: string): Promise<Conversation>
+  end(id: string): Promise<Conversation>
+  /** Upsert the requesting user's read marker to now (open a conversation). */
+  markRead(id: string): Promise<void>
+  /** Remove the marker — the conversation reads as unread again. */
+  markUnread(id: string): Promise<void>
+  /** Unread-conversation counts for the requesting user (envelope + badges). */
+  unreadCounts(): Promise<UnreadCounts>
+}
+
+class ConversationServiceImpl implements ConversationService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListConversationsQuery = {}): Promise<ListResponse<Conversation>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/conversations`, query)
+  }
+
+  get(id: string): Promise<Conversation> {
+    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}`)
+  }
+
+  end(id: string): Promise<Conversation> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/end`)
+  }
+
+  markRead(id: string): Promise<void> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/read`)
+  }
+
+  markUnread(id: string): Promise<void> {
+    return this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(id)}/read`)
+  }
+
+  unreadCounts(): Promise<UnreadCounts> {
+    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/conversations/unread-counts`)
+  }
+}
+
+/** Messages within a conversation (ordered by occurred_at) + outbound send + reactions. */
+export interface MessageService {
+  listByConversation(conversationId: string, query?: ListMessagesQuery): Promise<ListResponse<Message>>
+  send(request: SendMessageRequest): Promise<Message>
+  /** Aggregated reactions on one message (also rides on Message.reactions). */
+  getReactions(messageId: string): Promise<Reaction[]>
+  /**
+   * Place an emoji (connector-native token) via the message's connector.
+   * Rejected with `reactions_not_supported` on reaction-less channels — gate
+   * the affordance on the connection's `supports_reactions` / `reactions`.
+   */
+  addReaction(messageId: string, emoji: string): Promise<Reaction[]>
+  removeReaction(messageId: string, emoji: string): Promise<Reaction[]>
+}
+
+class MessageServiceImpl implements MessageService {
+  constructor(private readonly client: ProteosClient) {}
+
+  listByConversation(conversationId: string, query: ListMessagesQuery = {}): Promise<ListResponse<Message>> {
+    return this.client.requestWithQuery(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/conversations/${encodeURIComponent(conversationId)}/messages`,
+      query,
+    )
+  }
+
+  send(request: SendMessageRequest): Promise<Message> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/messages/send`, request)
+  }
+
+  async getReactions(messageId: string): Promise<Reaction[]> {
+    const response: ListReactionsResponse = await this.client.request(
+      'GET',
+      `${CONVERSATION_BASE_PATH}/messages/${encodeURIComponent(messageId)}/reactions`,
+    )
+    return response.data
+  }
+
+  async addReaction(messageId: string, emoji: string): Promise<Reaction[]> {
+    const response: ListReactionsResponse = await this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/messages/${encodeURIComponent(messageId)}/reactions`,
+      { emoji },
+    )
+    return response.data
+  }
+
+  async removeReaction(messageId: string, emoji: string): Promise<Reaction[]> {
+    const response: ListReactionsResponse = await this.client.request(
+      'DELETE',
+      `${CONVERSATION_BASE_PATH}/messages/${encodeURIComponent(messageId)}/reactions/${encodeURIComponent(emoji)}`,
+    )
+    return response.data
+  }
+}
+
+/** Rules binding inbound messages to agents. */
+export interface AgentListenerService {
+  list(query?: ListAgentListenersQuery): Promise<ListResponse<AgentListener>>
+  get(id: string): Promise<AgentListener>
+  create(request: CreateAgentListenerRequest): Promise<AgentListener>
+  update(id: string, request: UpdateAgentListenerRequest): Promise<AgentListener>
+  delete(id: string): Promise<void>
+}
+
+class AgentListenerServiceImpl implements AgentListenerService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(query: ListAgentListenersQuery = {}): Promise<ListResponse<AgentListener>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/agent-listeners`, query)
+  }
+
+  get(id: string): Promise<AgentListener> {
+    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`)
+  }
+
+  create(request: CreateAgentListenerRequest): Promise<AgentListener> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/agent-listeners`, request)
+  }
+
+  update(id: string, request: UpdateAgentListenerRequest): Promise<AgentListener> {
+    return this.client.request('PATCH', `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request('DELETE', `${CONVERSATION_BASE_PATH}/agent-listeners/${encodeURIComponent(id)}`)
+  }
+}
+
+/** Batch transcription of stored audio files + materialization. */
+export interface TranscriptionService {
+  /**
+   * Kicks off transcription asynchronously — resolves immediately with a
+   * PROCESSING entity; the provider runs off-request. Poll `get(id)` until the
+   * status is `completed` (or `failed`), then `materialize`.
+   */
+  createFromFile(request: CreateTranscriptionRequest): Promise<Transcription>
+  list(query?: ListTranscriptionsQuery): Promise<ListResponse<Transcription>>
+  get(id: string): Promise<Transcription>
+  /** Turns a completed transcription into an adhoc/meeting conversation. */
+  materialize(id: string, request?: MaterializeTranscriptionRequest): Promise<Conversation>
+}
+
+class TranscriptionServiceImpl implements TranscriptionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  createFromFile(request: CreateTranscriptionRequest): Promise<Transcription> {
+    return this.client.request('POST', `${CONVERSATION_BASE_PATH}/transcriptions`, request)
+  }
+
+  list(query: ListTranscriptionsQuery = {}): Promise<ListResponse<Transcription>> {
+    return this.client.requestWithQuery('GET', `${CONVERSATION_BASE_PATH}/transcriptions`, query)
+  }
+
+  get(id: string): Promise<Transcription> {
+    return this.client.request('GET', `${CONVERSATION_BASE_PATH}/transcriptions/${encodeURIComponent(id)}`)
+  }
+
+  materialize(id: string, request: MaterializeTranscriptionRequest = {}): Promise<Conversation> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/transcriptions/${encodeURIComponent(id)}/materialize`,
+      request,
+    )
+  }
+}
+
+export type * from './types.js'
+// Re-export voice types (the live dictation stream lives on this service now)
+export type {
+  TranscribeStreamOptions,
+  TranscriptResult,
+  VoiceService,
+  VoiceTranscriptionStream,
+} from './voice.js'