Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
23.7 KB
Raw Blame
import { config } from './config.js'
import { ApiError, requestJson } from './httpClient.js'
import {
  DesktopEnvironmentDiscovery,
  DesktopReleasePolicy,
  EntityChangeStreamEvent,
  ExternalChannelAccount,
  ExternalChannelTarget,
  LoginResult,
  PendingWorkflowApproval,
  RpcScope,
  SdkNotificationSummary,
  SessionMe,
  TeamAgents,
  TeamContexts,
  TeamDirectoryResult,
  TeamMember,
  TeamSummary,
  UserAgents,
  UserContexts,
  UserNotificationPreferences,
  WorkflowApprovalDecisionResult,
  WorkflowNotificationStreamEvent,
  WorkflowRecipeListResult,
  WorkflowRunArtifactsResult,
  WorkflowRunCompletedNotification,
  WorkflowRunsResult,
} from './types.js'
import { boundedErrorExcerpt } from './upstreamErrors.js'

function url(path: string): string {
  return `${config.externalRestApiBaseUrl.replace(/\/+$/, '')}${path}`
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return Boolean(value && typeof value === 'object' && !Array.isArray(value))
}

function parseEntityChangeStreamFrame(value: unknown): EntityChangeStreamEvent | null {
  if (!isRecord(value)) throw new Error('Entity change stream contained a malformed frame')
  const cursor = typeof value.cursor === 'string' ? value.cursor : ''
  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(cursor)) {
    throw new Error('Entity change stream contained an invalid cursor')
  }
  if (value.schemaVersion !== 1 || typeof value.type !== 'string') {
    throw new Error('Entity change stream contained an unsupported schema version')
  }
  if (value.type === 'resync_required' || value.type === 'scope.invalidated') {
    if (!Array.isArray(value.scopes) || value.scopes.length === 0)
      throw new Error('Entity change stream contained invalid scopes')
    const scopes = value.scopes.filter(
      (scope): scope is 'gfs' | 'authorization' => scope === 'gfs' || scope === 'authorization'
    )
    if (scopes.length === 0) return null
    return {
      type: value.type,
      schemaVersion: 1,
      cursor,
      scopes,
    }
  }
  if (value.type === 'heartbeat') {
    if (typeof value.observedAt !== 'string') {
      throw new Error('Entity change stream contained an invalid heartbeat')
    }
    return {
      type: 'heartbeat',
      schemaVersion: 1,
      cursor,
      observedAt: value.observedAt,
    }
  }
  if (value.type === 'stream.closing') {
    const reasons = ['max_lifetime', 'session_expired', 'server_shutdown', 'slow_consumer']
    if (typeof value.reason !== 'string' || !reasons.includes(value.reason)) {
      return null
    }
    return {
      type: 'stream.closing',
      schemaVersion: 1,
      cursor,
      reason: value.reason as Extract<
        EntityChangeStreamEvent,
        { type: 'stream.closing' }
      >['reason'],
    }
  }
  // Schema v1 extensions are defined to be safely ignorable by older clients.
  return null
}

function parsePendingWorkflowApproval(value: unknown): PendingWorkflowApproval | null {
  if (!isRecord(value)) return null
  const payload = isRecord(value.payload) ? value.payload : null
  const target = isRecord(value.target) ? value.target : null
  if (
    typeof value.id !== 'string' ||
    typeof value.recipeNamespace !== 'string' ||
    typeof value.recipeName !== 'string' ||
    typeof value.requestedAt !== 'string' ||
    typeof value.expiresAt !== 'string' ||
    !payload ||
    typeof payload.message !== 'string' ||
    !target
  ) {
    return null
  }

  const correlation = isRecord(value.correlation)
    ? {
        ...(typeof value.correlation.taskId === 'string'
          ? { taskId: value.correlation.taskId }
          : {}),
        ...(typeof value.correlation.stepId === 'string'
          ? { stepId: value.correlation.stepId }
          : {}),
      }
    : null

  return {
    id: value.id,
    recipeNamespace: value.recipeNamespace,
    recipeName: value.recipeName,
    requestedAt: value.requestedAt,
    expiresAt: value.expiresAt,
    payload: {
      message: payload.message,
      ...(Array.isArray(payload.options)
        ? { options: payload.options.map(option => String(option)) }
        : {}),
      ...(Object.prototype.hasOwnProperty.call(payload, 'metadata')
        ? { metadata: payload.metadata }
        : {}),
    },
    correlation,
    target: {
      userId: typeof target.userId === 'string' ? target.userId : null,
      teamId: typeof target.teamId === 'string' ? target.teamId : null,
      teamName: typeof target.teamName === 'string' ? target.teamName : null,
    },
  }
}

function parseWorkflowRunCompletedNotification(
  value: unknown
): WorkflowRunCompletedNotification | null {
  if (!isRecord(value)) return null
  const target = isRecord(value.target) ? value.target : null
  if (
    typeof value.workflowRunId !== 'string' ||
    typeof value.approvalRequestId !== 'string' ||
    typeof value.recipeNamespace !== 'string' ||
    typeof value.recipeName !== 'string' ||
    !['Succeeded', 'Failed', 'Canceled'].includes(String(value.phase || '')) ||
    typeof value.completedAt !== 'string' ||
    !target
  ) {
    return null
  }

  return {
    workflowRunId: value.workflowRunId,
    approvalRequestId: value.approvalRequestId,
    recipeNamespace: value.recipeNamespace,
    recipeName: value.recipeName,
    phase: value.phase as WorkflowRunCompletedNotification['phase'],
    completedAt: value.completedAt,
    message: typeof value.message === 'string' ? value.message : null,
    target: {
      userId: typeof target.userId === 'string' ? target.userId : null,
      teamId: typeof target.teamId === 'string' ? target.teamId : null,
      teamName: typeof target.teamName === 'string' ? target.teamName : null,
    },
  }
}

function parseSdkNotificationSummary(value: unknown): SdkNotificationSummary | null {
  if (!isRecord(value)) return null
  const actionRef = isRecord(value.actionRef)
    ? {
        type: String(value.actionRef.type || ''),
        id: String(value.actionRef.id || ''),
        ...(typeof value.actionRef.urlRef === 'string' ? { urlRef: value.actionRef.urlRef } : {}),
      }
    : null
  if (
    typeof value.notificationId !== 'string' ||
    value.origin !== 'plugin_workload_sdk' ||
    typeof value.recipeNamespace !== 'string' ||
    typeof value.recipeName !== 'string' ||
    typeof value.callerRef !== 'string' ||
    typeof value.eventType !== 'string' ||
    typeof value.title !== 'string' ||
    typeof value.body !== 'string'
  ) {
    return null
  }
  const data =
    isRecord(value.data) && !Array.isArray(value.data)
      ? (value.data as Record<string, unknown>)
      : {}
  return {
    notificationId: value.notificationId,
    origin: 'plugin_workload_sdk',
    recipeNamespace: value.recipeNamespace,
    recipeName: value.recipeName,
    callerRef: value.callerRef,
    eventType: value.eventType,
    title: value.title,
    body: value.body,
    data,
    actionRef: actionRef && actionRef.type && actionRef.id ? actionRef : null,
    deliveryPolicyRef: typeof value.deliveryPolicyRef === 'string' ? value.deliveryPolicyRef : null,
  }
}

function parseWorkflowNotificationStreamEvent(
  value: unknown
): WorkflowNotificationStreamEvent | null {
  if (!isRecord(value) || typeof value.type !== 'string') return null
  if (value.type === 'notification.snapshot') {
    if (!Array.isArray(value.items) || typeof value.observedAt !== 'string') return null
    const items = value.items.map(parsePendingWorkflowApproval)
    if (items.some(item => item === null)) return null
    return {
      type: 'notification.snapshot',
      items: items as PendingWorkflowApproval[],
      cursor: typeof value.cursor === 'string' ? value.cursor : null,
      observedAt: value.observedAt,
    }
  }
  if (value.type === 'approval.requested') {
    const approval = parsePendingWorkflowApproval(value.approval)
    if (
      !approval ||
      typeof value.id !== 'string' ||
      typeof value.cursor !== 'string' ||
      typeof value.observedAt !== 'string'
    ) {
      return null
    }
    return {
      type: 'approval.requested',
      id: value.id,
      cursor: value.cursor,
      approval,
      observedAt: value.observedAt,
    }
  }
  if (value.type === 'approval.updated') {
    const status = typeof value.status === 'string' ? value.status : ''
    if (
      typeof value.id !== 'string' ||
      typeof value.cursor !== 'string' ||
      typeof value.approvalRequestId !== 'string' ||
      typeof value.observedAt !== 'string' ||
      !['approved', 'denied', 'cancelled', 'expired', 'consumed'].includes(status)
    ) {
      return null
    }
    return {
      type: 'approval.updated',
      id: value.id,
      cursor: value.cursor,
      approvalRequestId: value.approvalRequestId,
      status: status as 'approved' | 'denied' | 'cancelled' | 'expired' | 'consumed',
      observedAt: value.observedAt,
    }
  }
  if (value.type === 'workflow.run.completed') {
    const workflowRun = parseWorkflowRunCompletedNotification(value.workflowRun)
    if (
      !workflowRun ||
      typeof value.id !== 'string' ||
      typeof value.cursor !== 'string' ||
      typeof value.observedAt !== 'string'
    ) {
      return null
    }
    return {
      type: 'workflow.run.completed',
      id: value.id,
      cursor: value.cursor,
      workflowRun,
      observedAt: value.observedAt,
    }
  }
  if (value.type === 'sdk.notification') {
    const notification = parseSdkNotificationSummary(value.notification)
    if (
      !notification ||
      typeof value.id !== 'string' ||
      typeof value.cursor !== 'string' ||
      typeof value.observedAt !== 'string'
    ) {
      return null
    }
    return {
      type: 'sdk.notification',
      id: value.id,
      cursor: value.cursor,
      notification,
      observedAt: value.observedAt,
    }
  }
  if (value.type === 'heartbeat' && typeof value.observedAt === 'string') {
    return { type: 'heartbeat', observedAt: value.observedAt }
  }
  if (
    value.type === 'stream.closing' &&
    typeof value.reason === 'string' &&
    typeof value.observedAt === 'string'
  ) {
    return { type: 'stream.closing', reason: value.reason, observedAt: value.observedAt }
  }
  return null
}

async function readErrorBody(response: Response): Promise<string> {
  try {
    return await response.text()
  } catch (error) {
    return error instanceof Error
      ? `Failed to read error body: ${error.message}`
      : 'Failed to read error body'
  }
}

export class AuthClient {
  async health(): Promise<{ status: string }> {
    return requestJson<{ status: string }>('GET', url('/health'))
  }

  /**
   * Health check against an EXPLICIT external-rest-api base URL rather than the
   * active `config` one. Used to probe a candidate backend (e.g. localhost)
   * without mutating the active runtime config. Pass a short-lived `signal`
   * (e.g. `AbortSignal.timeout(...)`) to keep the probe snappy — the app-wide
   * timeout still applies as an upper bound via `withTimeout`.
   */
  async healthAt(baseUrl: string, signal?: AbortSignal): Promise<{ status: string }> {
    const normalized = baseUrl.replace(/\/+$/, '')
    return requestJson<{ status: string }>('GET', `${normalized}/health`, { signal })
  }

  async getDesktopEnvironment(): Promise<DesktopEnvironmentDiscovery> {
    return requestJson<DesktopEnvironmentDiscovery>('GET', url('/api/v1/desktop/environment'))
  }

  async getDesktopReleasePolicy(token: string): Promise<DesktopReleasePolicy> {
    return requestJson<DesktopReleasePolicy>('GET', url('/api/v1/desktop/release'), { token })
  }

  async googleLogin(idToken: string): Promise<LoginResult> {
    return requestJson<LoginResult>('POST', url('/api/v1/auth/google'), {
      body: { idToken },
    })
  }

  async passwordLogin(email: string, password: string): Promise<LoginResult> {
    return requestJson<LoginResult>('POST', url('/api/v1/auth/password-login'), {
      body: { email, password },
    })
  }

  async getMe(sessionToken: string): Promise<SessionMe> {
    return requestJson<SessionMe>('GET', url('/api/v1/me'), {
      token: sessionToken,
    })
  }

  async listTeams(sessionToken: string): Promise<{ currentTeamId: string; items: TeamSummary[] }> {
    return requestJson<{ currentTeamId: string; items: TeamSummary[] }>(
      'GET',
      url('/api/v1/me/teams'),
      {
        token: sessionToken,
      }
    )
  }

  async getInitialTeamDirectory(sessionToken: string): Promise<TeamDirectoryResult> {
    return requestJson<TeamDirectoryResult>('GET', url('/api/v1/me/teams/directory'), {
      token: sessionToken,
    })
  }

  async switchTeam(
    sessionToken: string,
    teamId: string
  ): Promise<{ token: string; team: TeamSummary }> {
    return requestJson<{ token: string; team: TeamSummary }>(
      'POST',
      url('/api/v1/me/switch-team'),
      {
        token: sessionToken,
        body: { teamId },
      }
    )
  }

  async getMyContexts(sessionToken: string): Promise<UserContexts> {
    return requestJson<UserContexts>('GET', url('/api/v1/me/contexts'), { token: sessionToken })
  }

  async getMyAgents(sessionToken: string): Promise<UserAgents> {
    return requestJson<UserAgents>('GET', url('/api/v1/me/agents'), { token: sessionToken })
  }

  async getTeamContexts(sessionToken: string): Promise<TeamContexts> {
    return requestJson<TeamContexts>('GET', url('/api/v1/team/contexts'), { token: sessionToken })
  }

  async getTeamAgents(sessionToken: string): Promise<TeamAgents> {
    return requestJson<TeamAgents>('GET', url('/api/v1/team/agents'), { token: sessionToken })
  }

  async getTeamMembers(sessionToken: string): Promise<{ items: TeamMember[] }> {
    return requestJson<{ items: TeamMember[] }>('GET', url('/api/v1/team/members'), {
      token: sessionToken,
    })
  }

  async listPendingWorkflowApprovals(
    sessionToken: string,
    limit = 20
  ): Promise<{ items: PendingWorkflowApproval[] }> {
    const query = new URLSearchParams({ limit: String(limit) })
    return requestJson<{ items: PendingWorkflowApproval[] }>(
      'GET',
      url(`/api/v1/workflow-approvals?${query.toString()}`),
      { token: sessionToken }
    )
  }

  async decideWorkflowApproval(
    sessionToken: string,
    approvalId: string,
    decision: 'approve' | 'deny',
    note?: string
  ): Promise<WorkflowApprovalDecisionResult> {
    return requestJson<WorkflowApprovalDecisionResult>(
      'POST',
      url(`/api/v1/workflow-approvals/${encodeURIComponent(approvalId)}/decide`),
      {
        token: sessionToken,
        body: note ? { decision, note } : { decision },
      }
    )
  }

  async acknowledgeNotificationDelivery(
    sessionToken: string,
    notificationId: string
  ): Promise<{ ok: boolean; status: string }> {
    return requestJson<{ ok: boolean; status: string }>(
      'POST',
      url(`/api/v1/notifications/${encodeURIComponent(notificationId)}/ack`),
      { token: sessionToken }
    )
  }

  async getNotificationPreferences(sessionToken: string): Promise<UserNotificationPreferences> {
    return requestJson<UserNotificationPreferences>(
      'GET',
      url('/api/v1/me/notification-preferences'),
      { token: sessionToken }
    )
  }

  async listExternalChannelTargets(
    sessionToken: string
  ): Promise<{ items: ExternalChannelTarget[] }> {
    return requestJson<{ items: ExternalChannelTarget[] }>(
      'GET',
      url('/api/v1/workflow-approval-mediums/targets'),
      { token: sessionToken }
    )
  }

  async listExternalChannelAccounts(
    sessionToken: string
  ): Promise<{ items: ExternalChannelAccount[] }> {
    return requestJson<{ items: ExternalChannelAccount[] }>(
      'GET',
      url('/api/v1/workflow-approval-mediums'),
      { token: sessionToken }
    )
  }

  async updateNotificationPreferences(
    sessionToken: string,
    body: {
      preferredMedium: 'telegram' | 'slack' | null
      channelFallbackEnabled: boolean
    }
  ): Promise<UserNotificationPreferences> {
    return requestJson<UserNotificationPreferences>(
      'PUT',
      url('/api/v1/me/notification-preferences'),
      { token: sessionToken, body }
    )
  }

  async openWorkflowNotificationStream(
    sessionToken: string,
    onEvent: (event: WorkflowNotificationStreamEvent) => void,
    signal: AbortSignal
  ): Promise<void> {
    const response = await fetch(url('/api/v1/notifications/stream'), {
      method: 'GET',
      headers: {
        accept: 'application/x-ndjson',
        authorization: `Bearer ${sessionToken}`,
      },
      signal,
    })
    if (!response.ok) {
      const body = await readErrorBody(response)
      throw new ApiError(
        `Notification stream failed (${response.status}): ${boundedErrorExcerpt(body) || response.statusText}`,
        response.status,
        body
      )
    }
    if (!response.body) {
      throw new Error('Notification stream missing response body')
    }

    onEvent({ type: 'open' })
    const reader = response.body.getReader()
    const decoder = new TextDecoder()
    let buffer = ''

    const processChunk = (chunk: string) => {
      buffer += chunk
      while (true) {
        const newline = buffer.indexOf('\n')
        if (newline === -1) break
        const rawLine = buffer.slice(0, newline).trim()
        buffer = buffer.slice(newline + 1)
        if (!rawLine) continue
        try {
          const parsed = parseWorkflowNotificationStreamEvent(JSON.parse(rawLine) as unknown)
          if (parsed) {
            onEvent(parsed)
          } else {
            onEvent({ type: 'error', message: 'Invalid notification stream payload' })
          }
        } catch {
          onEvent({ type: 'error', message: 'Invalid notification stream JSON' })
        }
      }
    }

    while (true) {
      const { done, value } = await reader.read()
      if (done) break
      processChunk(decoder.decode(value, { stream: true }))
    }
    const trailing = decoder.decode()
    if (trailing) processChunk(trailing)
  }

  async openEntityChangeStream(
    sessionToken: string,
    _cursor: string | null,
    onEvent: (event: EntityChangeStreamEvent) => void,
    signal: AbortSignal
  ): Promise<void> {
    const streamUrl = new URL(url('/api/v1/entity-changes/stream'))
    // The user stream intentionally starts from a fixed coarse invalidation
    // checkpoint. Sending the local cursor would disclose feed position while
    // the server correctly ignores it to prevent hidden-change timing leaks.
    const response = await fetch(streamUrl, {
      method: 'GET',
      headers: {
        accept: 'application/x-ndjson',
        authorization: `Bearer ${sessionToken}`,
      },
      signal,
    })
    if (!response.ok) {
      const body = await readErrorBody(response)
      throw new ApiError(
        `Entity change stream failed (${response.status}): ${boundedErrorExcerpt(body) || response.statusText}`,
        response.status,
        body,
        response.headers.get('retry-after')
      )
    }
    if (!response.body) throw new Error('Entity change stream missing response body')

    onEvent({ type: 'open' })
    const reader = response.body.getReader()
    const decoder = new TextDecoder()
    let buffer = ''
    const processFrame = (rawLine: string) => {
      if (!rawLine.trim()) return
      let decoded: unknown
      try {
        decoded = JSON.parse(rawLine) as unknown
      } catch {
        throw new Error('Entity change stream contained invalid JSON')
      }
      const frame = parseEntityChangeStreamFrame(decoded)
      if (!frame) return
      onEvent(frame)
    }
    const processChunk = (chunk: string) => {
      buffer += chunk
      if (buffer.length > 16 * 1024 && !buffer.includes('\n')) {
        throw new Error('Entity change stream frame exceeded the size limit')
      }
      while (true) {
        const newline = buffer.indexOf('\n')
        if (newline === -1) break
        const line = buffer.slice(0, newline)
        buffer = buffer.slice(newline + 1)
        if (line.length > 16 * 1024)
          throw new Error('Entity change stream frame exceeded the size limit')
        processFrame(line)
      }
    }

    try {
      while (true) {
        const { done, value } = await reader.read()
        if (done) break
        processChunk(decoder.decode(value, { stream: true }))
      }
      processChunk(decoder.decode())
      if (buffer.trim()) processFrame(buffer)
    } catch (error) {
      await reader.cancel().catch(() => undefined)
      throw error
    } finally {
      reader.releaseLock()
    }
  }

  async listWorkflows(sessionToken: string): Promise<WorkflowRecipeListResult> {
    return requestJson<WorkflowRecipeListResult>('GET', url('/api/v1/workflows'), {
      token: sessionToken,
      retryTransientOnce: true,
    })
  }

  async readWorkflow(sessionToken: string, ns: string, name: string): Promise<unknown> {
    return requestJson<unknown>(
      'GET',
      url(`/api/v1/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}`),
      { token: sessionToken, retryTransientOnce: true }
    )
  }

  async getWorkflowHealth(sessionToken: string, ns: string, name: string): Promise<unknown> {
    return requestJson<unknown>(
      'GET',
      url(`/api/v1/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/health`),
      { token: sessionToken, retryTransientOnce: true }
    )
  }

  async triggerWorkflow(
    sessionToken: string,
    ns: string,
    name: string,
    body?: Record<string, unknown>,
    idempotencyKey?: string
  ): Promise<unknown> {
    return requestJson<unknown>(
      'POST',
      url(`/api/v1/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/trigger`),
      {
        token: sessionToken,
        body,
        headers: idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined,
        retryTransientOnce: Boolean(idempotencyKey),
      }
    )
  }

  async listWorkflowRuns(
    sessionToken: string,
    ns: string,
    name: string,
    limit?: number
  ): Promise<WorkflowRunsResult> {
    const query = new URLSearchParams()
    if (limit) query.set('limit', String(limit))
    const qs = query.toString()
    return requestJson<WorkflowRunsResult>(
      'GET',
      url(
        `/api/v1/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/runs${qs ? `?${qs}` : ''}`
      ),
      { token: sessionToken, retryTransientOnce: true }
    )
  }

  async listWorkflowRunArtifacts(
    sessionToken: string,
    ns: string,
    name: string,
    runId: string
  ): Promise<WorkflowRunArtifactsResult> {
    return requestJson<WorkflowRunArtifactsResult>(
      'GET',
      url(
        `/api/v1/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/artifacts`
      ),
      { token: sessionToken, retryTransientOnce: true }
    )
  }

  async downloadWorkflowRunArtifact(
    sessionToken: string,
    ns: string,
    name: string,
    runId: string,
    artifactName: string
  ): Promise<Buffer> {
    const response = await fetch(
      url(
        `/api/v1/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactName)}/download`
      ),
      {
        method: 'GET',
        headers: { authorization: `Bearer ${sessionToken}` },
        signal: AbortSignal.timeout(config.requestTimeoutMs),
      }
    )
    if (!response.ok) {
      const body = await readErrorBody(response)
      throw new ApiError(
        `Download workflow artifact failed (${response.status}): ${boundedErrorExcerpt(body) || response.statusText}`,
        response.status,
        body
      )
    }
    return Buffer.from(await response.arrayBuffer())
  }

  async issueRpcToken(
    sessionToken: string,
    scopes: RpcScope[],
    hostRefs?: string[]
  ): Promise<{
    token: string
    accessScope: 'team' | 'user'
    teamId: string | null
    scopes: RpcScope[]
    hostRefs: string[]
    expiresInSeconds: number
  }> {
    return requestJson('POST', url('/api/v1/rpc/token'), {
      token: sessionToken,
      body: {
        scopes,
        hostRefs: hostRefs && hostRefs.length ? hostRefs : undefined,
      },
    })
  }
}