connect

<div align="center"> # @vinkius/connect ### Give your AI application real-world capabilities. [](https://www.npmjs.com/package/@vinkius/connect) [](https://vinkius.com) [](https://vinkius.com) </div> **Vinkius Connect** gives the AI application you're building access to thousands of tools, services, and systems — so your AI can take action for each user. Your application identifies the user. Vinkius handles the connectivity, authentication, permissions, protocols, and execution behind the capabilities that user has connected. ``` Your AI Application │ ▼ User │ ▼ Connectors │ ▼ Capabilities │ ▼ Action ``` ### Connectors provide access. Capabilities provide action. A connector connects your user to an external system. A capability is what your AI can actually do with it. ``` GitHub connector │ ├── list repositories ├── create issue ├── create pull request ├── review code └── search code ``` ```ts const capabilities = await vinkius.user('alice_123').capabilities(); // → the capabilities available to this user ``` Built on the [Vinkius AI Connectivity Cloud](https://vinkius.com) — one managed connectivity layer that works with OpenAI, Anthropic, Gemini, the Vercel AI SDK, LangChain, LlamaIndex, Cloudflare Workers AI, and any OpenAI-compatible runtime. - **Capabilities, not integrations.** Your agent calls capabilities. Vinkius turns calls into action — authentication, permissions, protocol and execution are resolved for you. - **Connectors power capabilities.** A connector can provide many capabilities. Vinkius maintains the connectors and the capabilities your agents use through them. - **User-scoped.** Each user has their own connected connectors and capabilities, isolated from every other user. - **Portable.** Switch models, clients or frameworks without rebuilding your connectivity. Your capabilities stay yours. - **Zero runtime dependencies.** Runs on Node 18+, Bun, Deno, and edge runtimes. - **Security-first.** One secret to manage. Credentials are write-only. Every request carries identity. See [SECURITY.md](./SECURITY.md). ## Contents - [Get your API credentials](#get-your-api-credentials) - [Install](#install) - [Quick start](#quick-start) - [Concepts](#concepts) - [Connect a connector](#connect-a-connector) - [Execute a capability](#execute-a-capability) - [Framework adapters](#framework-adapters) - [Low-level API](#low-level-api) - [Configuration](#configuration) - [Errors](#errors) - [Security](#security) - [Compatibility](#compatibility) - [License](#license) ## Get your API credentials Vinkius Connect authenticates with two values from a Vinkius Cloud **Application**: | Value | Prefix | What it is | | -------- | ------------- | -------------------------------------------------------------------------- | | `appId` | `vk_app_…` | The Application's public id — identifies your tenant | | `apiKey` | `vk_app_sk_…` | An **Application Key** — the secret your backend uses to act for its users | To create them in the [Vinkius Cloud](https://cloud.vinkius.com) dashboard: 1. Open **Build AI Apps** (`/ai-agents`) and click **New AI Application**. Give it a name (e.g. `Acme Copilot`) and create it. 2. Open the application. Your **App ID** (`vk_app_…`) is shown under the app name and in the page URL — copy it into `appId`. 3. Go to the **App Keys** tab → **New Key**. Select the permissions your backend needs, then **Create Key**. 4. The **Application Key** (`vk_app_sk_…`) is shown **once**, in a _"Copy this key now"_ dialog. Copy it into `apiKey` — it cannot be retrieved afterward. You can **rotate** or **revoke** a key anytime from the same **App Keys** tab. Rotating invalidates the old key immediately and reveals the new one once. > **Keep `vk_app_sk_…` server-side only** — an environment variable or your secrets > manager. Never ship it to a browser, mobile app, or any client the user controls. ```bash # .env (server-side) VINKIUS_APP_ID=vk_app_xxxxxxxxxxxxxxxx VINKIUS_APP_KEY=vk_app_sk_xxxxxxxxxxxxxxxxxxxxxxxx ``` ## Install ```bash npm install @vinkius/connect # or: pnpm add @vinkius/connect · yarn add @vinkius/connect · bun add @vinkius/connect ``` ## Quick start Give your agent the capabilities a specific user has connected — one line: ```ts import { Vinkius } from '@vinkius/connect'; const vinkius = new Vinkius({ appId: process.env.VINKIUS_APP_ID!, apiKey: process.env.VINKIUS_APP_KEY!, }); // The AI capabilities this user's connectors provide const capabilities = await vinkius.user('alice_123').capabilities(); ``` End-to-end with OpenAI — three imports, and the model can call your user's real capabilities: ```ts import OpenAI from 'openai'; import { Vinkius } from '@vinkius/connect'; import { toOpenAITools, runOpenAIToolCall } from '@vinkius/connect/openai'; const openai = new OpenAI(); const vinkius = new Vinkius({ appId: process.env.VINKIUS_APP_ID!, apiKey: process.env.VINKIUS_APP_KEY!, }); const capabilities = await vinkius.user('alice_123').capabilities(); const completion = await openai.chat.completions.create({ model: 'your-model', messages: [{ role: 'user', content: 'Open a GitHub issue titled "Ship it"' }], tools: toOpenAITools(capabilities), }); const call = completion.choices[0]?.message.tool_calls?.[0]; if (call) { const result = await runOpenAIToolCall(capabilities, call); console.log(result.content); } ``` No per-connector glue, no OAuth plumbing, no storing tokens. The user connects GitHub once in your app; every agent turn just works. ## Concepts The SDK is split into two planes over the same `vk_app_sk_*` credential: - **Control plane** — provisioning and state: `users`, `connectors`, `credentials`, `catalog`. - **Execution plane** — runtime: `capabilities()` and `execute()`. `user.capabilities()` is the primary contract: it returns the AI capabilities available to **that user**, as executable, framework-neutral objects. A connector is not a capability — a single connector can provide many capabilities. ```ts const user = vinkius.user('alice_123'); await user.connectors(); // connected connectors + status await user.capabilities(); // all capabilities for this user await user.capabilities({ include: ['github', 'slack'] }); // subset ``` Users are addressed by **your own `external_id`** (`"alice_123"`), which comes from your auth system. There is no Vinkius user id to resolve, cache, or store — the platform derives everything from your Application credentials plus the id you pass. ## Connect a connector ```ts const github = vinkius.user('alice_123').connector('github'); await github.connect(); // provision the connection (idempotent) await github.credentials.set({ GITHUB_TOKEN: token }); // write-only console.log(await github.status()); // not_connected | needs_credentials | ready | disabled await github.capabilities(); // capabilities this connector provides await github.disconnect(); ``` Credentials are **write-only**: you can set them and check which keys are configured, but the SDK never returns secret values. ```ts await github.credentials.schema(); // fields this connector requires await github.credentials.status(); // which keys are configured (never the values) ``` ## Execute a capability ```ts const capabilities = await vinkius.user('alice_123').capabilities(); const result = await capabilities .findCapability('github__create_issue') ?.execute({ owner: 'acme', repo: 'product', title: 'Hello Vinkius' }); // result → { content: [{ type, text }], isError } ``` Your agent calls the capability. Vinkius resolves authentication, permissions, protocol and execution, then returns a structured result. A capability-level failure comes back as `isError: true` — a result, not a thrown exception — so your agent loop can feed the error back to the model and let it recover. ## Framework adapters Adapters are zero-dependency subpath exports that convert capabilities into your framework's **tool** format (each framework's own term). Where a framework needs one of its own factories, you inject it — no peer dependency, no version coupling. | Framework | Import | Notes | | -------------------------------- | -------------------------------- | ---------------------------------------- | | OpenAI (chat completions) | `@vinkius/connect/openai` | `toOpenAITools`, `runOpenAIToolCall` | | OpenAI Agents (`@openai/agents`) | `@vinkius/connect/openai-agents` | `toOpenAIAgentsTools` (inject `tool`) | | Anthropic (Messages) | `@vinkius/connect/anthropic` | `toAnthropicTools`, `runAnthropicToolUse` | | Google Gemini | `@vinkius/connect/gemini` | `toGeminiTools`, `runGeminiFunctionCall` | | Vercel AI SDK | `@vinkius/connect/ai-sdk` | `toAISDKTools` (inject `jsonSchema`) | | LangChain.js | `@vinkius/connect/langchain` | `toLangChainTools` (inject `tool`) | | LlamaIndex.TS | `@vinkius/connect/llamaindex` | `toLlamaIndexTools` (inject `tool`) | | Cloudflare Workers AI | `@vinkius/connect/workers-ai` | `toWorkersAITools` (for `runWithTools`) | | Any / neutral | `@vinkius/connect/json-schema` | `toJSONSchemaTools`, `executeByName` | ### OpenAI (chat completions) ```ts import { toOpenAITools, runOpenAIToolCall } from '@vinkius/connect/openai'; const capabilities = await vinkius.user('alice_123').capabilities(); const tools = toOpenAITools(capabilities); // … then runOpenAIToolCall(capabilities, toolCall) on each returned tool call. ``` ### Anthropic (Messages) ```ts import { toAnthropicTools } from '@vinkius/connect/anthropic'; const capabilities = await vinkius.user('alice_123').capabilities(); const tools = toAnthropicTools(capabilities); // pass as `tools` to messages.create ``` ### Google Gemini Produces function declarations for the unified Google GenAI SDK (`@google/genai`). ```ts import { toGeminiTools, runGeminiFunctionCall } from '@vinkius/connect/gemini'; const capabilities = await vinkius.user('alice_123').capabilities(); const response = await model.generateContent({ contents, tools: [{ functionDeclarations: toGeminiTools(capabilities) }], }); // on a returned functionCall part: const result = await runGeminiFunctionCall(capabilities, functionCall); ``` ### Vercel AI SDK Pass the AI SDK's own `jsonSchema` helper so parameters are wrapped correctly. ```ts import { jsonSchema } from 'ai'; import { toAISDKTools } from '@vinkius/connect/ai-sdk'; const capabilities = await vinkius.user('alice_123').capabilities(); const tools = toAISDKTools(capabilities, { jsonSchema }); ``` ### LangChain.js Inject LangChain's own `tool` factory so the returned objects are genuine, bindable LangChain tools — the adapter keeps zero dependencies. ```ts import { tool } from '@langchain/core/tools'; import { toLangChainTools } from '@vinkius/connect/langchain'; const capabilities = await vinkius.user('alice_123').capabilities(); const tools = toLangChainTools(capabilities, { tool }); const model = chat.bindTools(tools); ``` ### OpenAI Agents (`@openai/agents`) Distinct from the chat-completions adapter. Inject the Agents SDK's `tool` factory; the JSON Schema is passed as raw `parameters` with `strict: false`. ```ts import { Agent, tool } from '@openai/agents'; import { toOpenAIAgentsTools } from '@vinkius/connect/openai-agents'; const capabilities = await vinkius.user('alice_123').capabilities(); const agent = new Agent({ name: 'assistant', tools: toOpenAIAgentsTools(capabilities, { tool }), }); ``` ### LlamaIndex.TS Inject LlamaIndex's `tool` factory. Accepts raw JSON Schema — no Zod required. ```ts import { tool } from 'llamaindex'; import { toLlamaIndexTools } from '@vinkius/connect/llamaindex'; const capabilities = await vinkius.user('alice_123').capabilities(); const tools = toLlamaIndexTools(capabilities, { tool }); ``` ### Cloudflare Workers AI `toWorkersAITools` produces embedded function-calling tools (each with a bound `function`) for `runWithTools` from `@cloudflare/ai-utils`. ```ts import { runWithTools } from '@cloudflare/ai-utils'; import { toWorkersAITools } from '@vinkius/connect/workers-ai'; const capabilities = await vinkius.user('alice_123').capabilities(); const res = await runWithTools(env.AI, 'your-model', { messages, tools: toWorkersAITools(capabilities), }); ``` ### Neutral / other frameworks `toJSONSchemaTools` emits plain `{ name, description, parameters }` definitions — the lowest common denominator for any OpenAI-compatible provider or custom agent loop, with `executeByName` to dispatch. A few frameworks are intentionally covered by the adapters above rather than their own subpath: - **Mastra** — consumes Vercel AI SDK tools natively; use the `ai-sdk` adapter. - **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — requires a Zod schema and in-process MCP registration. Use the Messages-API `anthropic` adapter. - **CrewAI** — a Python framework. Use the neutral JSON Schema output as the bridge until a Vinkius Python SDK exists. ## Low-level API Every fluent call has a REST equivalent for full control: ```ts const connection = await vinkius.users.connections('alice_123').create({ connector: 'github' }); await vinkius.users .connections('alice_123') .credentials(connection.id) .set({ credentials: { GITHUB_TOKEN: '…' } }); ``` The fluent `credentials.set(values)` takes the flat map; the low-level client takes the HTTP envelope `{ credentials: values }`. ## Configuration ```ts new Vinkius({ appId: 'vk_app_…', apiKey: 'vk_app_sk_…', baseUrl: 'https://api.vinkius.com', // default timeoutMs: 30_000, // default maxRetries: 2, // default (idempotent requests only) fetch: globalThis.fetch, // override for tests/edge userAgent: 'acme-ai/1.0', // appended to the default User-Agent namespaceCapability: (connector, name) => `${connector}__${name}`, // default hooks: { onRequest: ({ method, url }) => {}, // headers/body are redacted onResponse: ({ status, requestId }) => {}, }, }); ``` ## Errors All failures are subclasses of `VinkiusError` with `status`, `code`, and `requestId`: `AuthError` · `NotFoundError` · `ValidationError` · `RateLimitError` · `QuotaError` · `OverageError` · `ConnectorNotConnectedError` · `ConnectionError` · `ConfigError` · `NotImplementedError`. Capability execution returns `{ content, isError }` — an `isError: true` result is returned, not thrown. Quota/overage limits surface as `QuotaError`/`OverageError`. ## Security - **One secret to manage.** Only `vk_app_sk_*` is sensitive; keep it server-side. - **Identity on every request.** Each call carries your `vk_app_*` app id and is validated against the key server-side — a key can only ever act for its own app. - **Write-only credentials.** Connector secrets can be set but never read back. The model never receives raw secrets. - **Redaction by design.** Authorization headers and secret values are stripped before any observability hook sees them. Full details and disclosure policy in [SECURITY.md](./SECURITY.md). ## Compatibility - **Runtimes:** Node 18+, Bun, Deno, and edge runtimes (anything with `fetch`). - **Modules:** ships dual ESM + CommonJS with bundled TypeScript types. - Discovery and provisioning (`users`, `connectors`, `credentials`, `catalog`) are available today. `user.capabilities()` and `capability.execute()` run on the Vinkius Execution Plane; make sure your Vinkius Cloud environment has it enabled. ## License [Apache 2.0](./LICENSE) © Vinkius