@nuxtagentic/integrations 0.0.0-stage → 0.1.0

package/runtime/server/api/integrations/catalog/[provider]/connection.post.ts

@@ -0,0 +1,242 @@
+import { readCommandBody } from '../../../../utils/request-body'
+import { defineEventHandler, getRequestURL, getRouterParam } from 'h3'
+import { assertGoogleMutation } from '@nuxtagentic/google/runtime/server/utils/google'
+import type { ConnectionSummary } from '@cloudconfig/core/connect'
+import {
+  connectOf,
+  defaultMcpApprovals,
+  getIntegrationContext,
+  listBindings,
+  toActionError,
+  toPublicConnection,
+  type Binding,
+} from '../../../../utils/integration-context'
+import { verifyIntegration, type Credentials } from '../../../../utils/integration-adapters'
+import { getIntegrationDefinition, type IntegrationScope } from '../../../../../shared/catalog'
+
+type Operation = 'start' | 'bind' | 'apiKey' | 'permissions' | 'disconnect' | 'target' | 'webhook'
+
+interface Body {
+  operation: Operation
+  scope?: IntegrationScope
+  /** MCP server URL for the custom MCP integration. */
+  server?: string
+  /** Values the provider needs before authorizing (Shopify store). */
+  fields?: Record<string, string>
+  credentials?: Credentials
+  label?: string
+  /** A Connect connection id (bind, target). */
+  connection?: number
+  /** An integration connection id (permissions, disconnect, webhook). */
+  binding?: number
+  target?: string
+  permissions?: string[]
+  approvals?: string[]
+  settings?: Record<string, string>
+  enabled?: boolean
+  rotate?: boolean
+}
+
+export default defineEventHandler(async (event) => {
+  assertGoogleMutation(event)
+  try {
+    const context = await getIntegrationContext(event)
+    const provider = getRouterParam(event, 'provider')!
+    const definition = getIntegrationDefinition(provider)
+    if (!definition) {
+      throw new Error('Choose a supported integration.')
+    }
+    const {
+      ownership,
+      name: integrationName,
+      auth,
+      fields: integrationFields,
+      actions: integrationActions,
+    } = definition
+    const { ownerId, manager, actor, api, workspace } = context
+    const body = await readCommandBody<Body>(event, 20000)
+    const {
+      operation,
+      scope: requestedScope,
+      settings: connectionSettings,
+      label: connectionLabel,
+      connection: connectConnectionId,
+      binding: bindingId,
+    } = body
+    const connect = await connectOf(context)
+    const request = new Request(getRequestURL(event))
+    const viewer = { ownerId, manager }
+    const scope: IntegrationScope = requestedScope ?? ownership[0]!
+    if (!ownership.includes(scope)) {
+      throw new Error(
+        scope === 'workspace'
+          ? `${integrationName} connects for one person only.`
+          : `${integrationName} is connected for the whole workspace by an admin.`,
+      )
+    }
+    const ownBinding = async (id: number | undefined): Promise<Binding> => {
+      const row = (await listBindings(context, { provider })).find((entry) => entry.id === id)
+      if (!row) {
+        throw new Error('Connection not found.')
+      }
+      return row
+    }
+
+    /** Attach a Connect connection to this integration, with every action allowed. */
+    const bind = async (summary: ConnectionSummary) => {
+      if (summary.status !== 'active') {
+        throw new Error('Finish setting up this connection first.')
+      }
+      const existing = (await listBindings(context, { provider })).find(
+        (row) => row.connectionId === summary.id,
+      )
+      if (existing) {
+        return toPublicConnection(existing, viewer)
+      }
+      let permissions = integrationActions.map((action) => action.id)
+      let approvals: string[] = []
+      if (auth.mcp) {
+        const tools = await connect.mcp(actor, summary.id).listTools()
+        permissions = tools.map((tool) => tool.name)
+        approvals = defaultMcpApprovals(tools)
+      }
+      const row = await api.integrationConnection.create({
+        provider,
+        workspace,
+        scope: summary.scope,
+        ...(summary.organizationId !== null ? { organizationId: summary.organizationId } : {}),
+        connectionId: summary.id,
+        connectionUid: summary.uid,
+        account: summary.label || summary.account.name,
+        enabled: true,
+        permissions,
+        approvals,
+        settings: connectionSettings ?? {},
+        ownerId,
+      })
+      return toPublicConnection(row, viewer)
+    }
+
+    switch (operation) {
+      case 'start': {
+        const { fields } = body
+        const returnTo = `/dashboard/integrations?integration=${encodeURIComponent(provider)}`
+        if (auth.mcp) {
+          const server = auth.mcp.server ?? body.server ?? ''
+          return connect.start(actor, request, {
+            provider: 'mcp',
+            scope,
+            returnTo,
+            fields: { server },
+            ...(connectionLabel ? { label: connectionLabel } : {}),
+          })
+        }
+        if (!auth.oauth) {
+          throw new Error(`${integrationName} connects with an API token.`)
+        }
+        return connect.start(actor, request, {
+          provider: auth.oauth.provider,
+          scope,
+          returnTo,
+          ...(auth.oauth.scopes ? { scopes: auth.oauth.scopes } : {}),
+          ...(fields ? { fields } : {}),
+          ...(connectionLabel ? { label: connectionLabel } : {}),
+          ...(connectConnectionId ? { connection: connectConnectionId } : {}),
+        })
+      }
+      case 'bind': {
+        const summary = await connect.get(actor, Number(connectConnectionId))
+        const expected = auth.mcp ? 'mcp' : auth.oauth?.provider
+        if (summary.provider !== expected) {
+          throw new Error(`That account is not a ${integrationName} connection.`)
+        }
+        const fixed = auth.mcp?.server
+        if (fixed && summary.server && new URL(summary.server).origin !== new URL(fixed).origin) {
+          throw new Error(`That MCP server is not ${integrationName}.`)
+        }
+        return bind(summary)
+      }
+      case 'target': {
+        const summary = await connect.selectTarget(
+          actor,
+          Number(connectConnectionId),
+          String(body.target ?? ''),
+        )
+        return bind(summary)
+      }
+      case 'apiKey': {
+        if (!auth.apiKey) {
+          throw new Error(
+            `${integrationName} connects with ${auth.mcp ? 'its MCP server' : 'OAuth'}.`,
+          )
+        }
+        const credentials = body.credentials ?? {}
+        if (
+          JSON.stringify(credentials).length > 16000 ||
+          Object.values(credentials).some((value) => typeof value !== 'string')
+        ) {
+          throw new Error('Provide valid connection credentials.')
+        }
+        if (!credentials.token) {
+          throw new Error('Enter the API access token for this connection.')
+        }
+        for (const field of integrationFields) {
+          if (!credentials[field.key]) {
+            throw new Error(`Enter ${field.label.toLowerCase()}.`)
+          }
+        }
+        // Prove the token works before storing it.
+        const account = await verifyIntegration(provider, credentials)
+        const summary = await connect.saveApiKey(actor, {
+          provider: `key-${provider}`,
+          scope,
+          fields: credentials,
+          account: { id: account, name: account },
+          ...(connectionLabel ? { label: connectionLabel } : {}),
+        })
+        return bind(summary)
+      }
+      case 'permissions': {
+        const { permissions, approvals, enabled } = body
+        const row = await ownBinding(bindingId)
+        return toPublicConnection(
+          await api.integrationConnection.update(row.id, {
+            ownerId: row.ownerId,
+            ...(permissions ? { permissions } : {}),
+            ...(approvals ? { approvals } : {}),
+            ...(connectionSettings ? { settings: connectionSettings } : {}),
+            ...(enabled !== undefined ? { enabled } : {}),
+            ...(connectionLabel !== undefined ? { label: connectionLabel.slice(0, 120) } : {}),
+          }),
+          viewer,
+        )
+      }
+      case 'disconnect': {
+        const row = await ownBinding(bindingId)
+        await api.integrationConnection.delete(row.id)
+        // Revoke the account at the vendor once no integration in this workspace uses it.
+        const stillUsed = (await listBindings(context)).some(
+          (entry) => entry.connectionId === row.connectionId,
+        )
+        if (row.connectionId && !stillUsed) {
+          await connect.remove(actor, row.connectionId).catch(() => {})
+        }
+        return { removed: row.id }
+      }
+      case 'webhook': {
+        const row = await ownBinding(bindingId)
+        const secret = body.rotate
+          ? await connect.rotateWebhookSecret(actor, row.connectionId)
+          : await connect.webhookSecret(actor, row.connectionId)
+        return {
+          url: `${getRequestURL(event).origin}/api/integration-hooks/${row.connectionUid}`,
+          secret,
+        }
+      }
+      default:
+        throw new Error('Choose a connection operation.')
+    }
+  } catch (cause) {
+    throw toActionError(cause)
+  }
+})

package/runtime/server/api/integrations/catalog/[provider]/tools.get.ts

@@ -0,0 +1,40 @@
+import { defineEventHandler, getQuery, getRouterParam } from 'h3'
+import {
+  connectOf,
+  getIntegrationContext,
+  isMcpIntegration,
+  listBindings,
+  toActionError,
+} from '../../../../utils/integration-context'
+import { isMcpWrite } from '../../../../../shared/catalog'
+
+/** Tools an MCP connection's server offers, for choosing what agents may use. */
+export default defineEventHandler(async (event) => {
+  try {
+    const context = await getIntegrationContext(event)
+    const provider = getRouterParam(event, 'provider')!
+    if (!isMcpIntegration(provider)) {
+      throw new Error('Only MCP servers list their tools.')
+    }
+    const binding = (await listBindings(context, { provider })).find(
+      (row) => row.id === Number(getQuery(event).binding),
+    )
+    if (!binding) {
+      throw new Error('Connection not found.')
+    }
+    const tools = await (
+      await connectOf(context)
+    )
+      .mcp(context.actor, binding.connectionId)
+      .listTools()
+    return tools.map((tool) => ({
+      name: tool.name,
+      title: tool.title ?? tool.annotations?.title ?? tool.name,
+      description: tool.description ?? '',
+      write: isMcpWrite(tool.annotations),
+      destructive: tool.annotations?.destructiveHint === true,
+    }))
+  } catch (cause) {
+    throw toActionError(cause)
+  }
+})

package/runtime/server/api/integrations/catalog/index.get.ts

@@ -0,0 +1,48 @@
+import { defineEventHandler } from 'h3'
+import type { ConnectionSummary } from '@cloudconfig/core/connect'
+import {
+  connectOf,
+  getIntegrationContext,
+  listBindings,
+  toPublicConnection,
+} from '../../../utils/integration-context'
+import { INTEGRATION_CATALOG } from '../../../../shared/catalog'
+
+export default defineEventHandler(async (event) => {
+  const context = await getIntegrationContext(event)
+  const connect = await connectOf(context)
+  const bindings = await listBindings(context)
+  // Connection health (expired, pending a choice) lives in Connect; sealed tokens never leave it.
+  let accounts: ConnectionSummary[] = []
+  try {
+    accounts = await connect.list(context.actor)
+  } catch {
+    // Without a sealing key there is nothing Connect can report yet.
+  }
+  const byId = new Map(accounts.map((account) => [account.id, account]))
+  return {
+    catalog: INTEGRATION_CATALOG,
+    connections: bindings.map((row) => {
+      const account = byId.get(row.connectionId)
+      return {
+        ...toPublicConnection(row, context),
+        status: account?.status ?? (row.connectionId ? 'error' : 'active'),
+        statusMessage: account?.statusMessage ?? '',
+      }
+    }),
+    /** Connect connections of this workspace that no integration uses yet, e.g. awaiting a choice. */
+    pending: accounts.filter((account) => account.status === 'pending'),
+    providers: connect
+      .providers()
+      .map(({ id, label, configured, missing, allow, startFields }) => ({
+        id,
+        label,
+        configured,
+        missing,
+        allow,
+        startFields,
+      })),
+    manager: context.manager,
+    organization: context.actor.organizationId !== null,
+  }
+})

package/runtime/server/api/integrations/catalog/tools.get.ts

@@ -0,0 +1,27 @@
+import { defineEventHandler } from 'h3'
+import {
+  getIntegrationContext,
+  listGrantedTools,
+  toActionError,
+} from '../../../utils/integration-context'
+
+/** The tools a saved agent may be given here: connected, enabled and permitted. */
+export default defineEventHandler(async (event) => {
+  try {
+    const context = await getIntegrationContext(event)
+    return (await listGrantedTools(context)).map(
+      ({ provider, action, name, description, parameters, approvalRequired, account, scope }) => ({
+        provider,
+        action,
+        name,
+        description,
+        parameters,
+        approvalRequired,
+        account,
+        scope,
+      }),
+    )
+  } catch (cause) {
+    throw toActionError(cause)
+  }
+})

package/runtime/server/plugins/connect-maintenance.ts

@@ -0,0 +1,30 @@
+import { defineNitroPlugin, useRuntimeConfig } from 'nitropack/runtime'
+import { connectOf, getDatabaseProvider } from '../utils/integration-context'
+
+/**
+ * On the Worker's cron trigger: refresh tokens before they lapse, re-seal after
+ * a key rotation, and revoke connections whose owner is gone.
+ */
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook('cloudflare:scheduled', async ({ env }) => {
+    const bindings = env as Record<string, unknown>
+    try {
+      const settings = useRuntimeConfig().cloudconfig as { d1Binding?: string; localDb?: string }
+      const database = await getDatabaseProvider(bindings, settings)
+      const connect = await connectOf({
+        database,
+        env: bindings,
+        request: new Request('https://maintenance.internal'),
+      })
+      const report = await connect.maintain()
+      if (Object.values(report).some(Boolean)) {
+        console.log('[integrations] Connection maintenance', JSON.stringify(report))
+      }
+    } catch (cause) {
+      console.error(
+        '[integrations] Connection maintenance failed:',
+        cause instanceof Error ? cause.message : cause,
+      )
+    }
+  })
+})

package/runtime/server/utils/approval-continuation.ts

@@ -0,0 +1,37 @@
+import { getAgentPlatform, type AgentScope } from '@cloudconfig/core/agents/platform'
+import type { H3Event } from 'h3'
+
+/** The continuation is server-only and immutable, and callers already checked the owner and workspace. */
+export async function notifyApproval(
+  event: H3Event,
+  id: number,
+  continuation: unknown,
+  env?: Record<string, unknown>,
+) {
+  if (!continuation || typeof continuation !== 'object') {
+    return
+  }
+  const { workflowId, automationRunId, agentScope, agentRunId } = continuation as {
+    workflowId?: string
+    automationRunId?: number
+    agentScope?: AgentScope
+    agentRunId?: string
+  }
+  if (workflowId && env?.AUTOMATION_RUNNER) {
+    const binding = env.AUTOMATION_RUNNER as {
+      get(
+        id: string,
+      ): Promise<{ sendEvent(event: { type: string; payload: unknown }): Promise<void> }>
+    }
+    await (
+      await binding.get(workflowId)
+    ).sendEvent({ type: `integration-approval-${id}`, payload: { approvalId: id } })
+  } else if (automationRunId && !env) {
+    await event.$fetch(`/api/automations/runs/${automationRunId}/resume`, { method: 'POST' })
+  }
+  // Queues the saved agent run on whichever platform holds it.
+  const agents = getAgentPlatform(env)
+  if (agentScope && agentRunId && agents) {
+    await (await agents.runs(agentScope)).resume(agentRunId)
+  }
+}