Three flows with connectFromSession — browse, link, and use workspace integrations.

Connect SDK

@auvy-os/connect-client is the typed HTTP SDK for Connect — OAuth integrations, tools, and credentials on a separate service from the AUVY OS API. AUVY OS routes under /v1/integrations return 410; call Connect directly.

This page covers the public browser API only (~7 methods). Triggers, credentials, OAuth apps, and full IntegrationsClient reference: see the advanced doc linked at the bottom of this page (same package, /advanced import).

Install

npm install @auvy-os/connect-client @auvy-os/client

Peer @auvy-os/client supplies transport and auth headers. For server-side tool execution, see connectRunTool on SDK introduction (@auvy-os/connect-client/server).

Flow 1 — Browse

Story: Show available integrations in a catalog picker.

import { connectFromSession } from '@auvy-os/connect-client'

const connect = connectFromSession({
  getAccessToken: () => session.access_token,
})

const integrations = await connect.list({ limit: 50 })
const slack = await connect.get(integrations[0].id)

Method	Purpose
`connectFromSession()`	Factory — publishable key + JWT (see auth note below)
`list()`	Workspace integration catalog
`get(id)`	One integration row

Auth: Browser Connect calls need a publishable key (NEXT_PUBLIC_AUVY_PUBLISHABLE_KEY or publishableKey) and getAccessToken returning the signed-in user JWT. Connect base URL comes from AUVY_CONNECT_URL or baseUrl.

Flow 2 — Link

Story: Connect Slack (or another provider) for the current user.

const { redirectUrl, connectionRequestId } = await connect.link(integrationId, {
  callbackUrl: 'https://app.example.com/connect/callback',
})

window.location.href = redirectUrl

// After redirect back with OAuth query params:
const { connected, connectedAccountId } = await connect.completeLink(integrationId, {
  connectionRequestId,
  query: Object.fromEntries(new URLSearchParams(window.location.search)),
})

Method	Purpose
`link(id, { callbackUrl? })`	Start OAuth — returns `redirectUrl` + `connectionRequestId`
`completeLink(id, { connectionRequestId, query? })`	Finish OAuth after callback

Store connectionRequestId from link() until the user returns; pass it to completeLink() with provider query params.

Flow 3 — Use

Story: Check connection status and list tools before invoking from an agent.

const status = await connect.status(integrationId)
if (!status.connected) {
  // prompt Flow 2
}

const tools = await connect.tools(integrationId)
console.log(tools.map((t) => t.slug))

// Disconnect when the user opts out:
await connect.unlink(integrationId)

Method	Purpose
`status(id)`	Is this integration connected for the current user?
`tools(id)`	Tools exposed by the integration
`unlink(id)`	Disconnect the current user

Advanced surface

Need triggers, credentials, or integration admin CRUD? See Connect advanced (@auvy-os/connect-client/advanced).

Errors

import { ConnectError, CONNECT_ERROR_CODES } from '@auvy-os/connect-client'

try {
  await connect.get(integrationId)
} catch (e) {
  if (e instanceof ConnectError && e.code === CONNECT_ERROR_CODES.AUTH_REQUIRED) {
    // re-auth
  }
}

Full error matrix: Jobs, streaming, and errors.

SDK introduction — package map (AUVY OS vs Connect vs server)
Authentication — API key setup

Connect SDK

On this page