Documentação

AI Connect/Get started/Instalação

Instalação

Pergunte à IA sobre a Vinkius

Adicione @vinkius/connect a um runtime de servidor, configure as credenciais da aplicação e verifique a conexão com a API.

Instale o pacote no seu backend e crie uma única instância reutilizável de Vinkius. O cliente armazena configurações no nível da aplicação, não estado por usuário, portanto a mesma instância pode atender requisições de muitos usuários.

Pré-requisitos

  • Node.js 18 ou posterior, ou outro runtime de servidor que forneça fetch (Node 18+, Bun, Deno e runtimes de edge)
  • Um App ID do Vinkius que comece com vk_app_
  • Uma Application Key do Vinkius que comece com vk_app_sk_

Obtenha suas credenciais de API

O Vinkius Connect autentica com dois valores de uma Application do Vinkius Cloud:

ValorPrefixoO que é
appIdvk_app_...O id público da Application, que identifica seu tenant
apiKeyvk_app_sk_...Uma Application Key: o segredo que seu backend usa para agir em nome dos seus usuários

Para criá-los no painel do Vinkius Cloud:

  1. Abra Build AI Apps (/ai-agents) e clique em New AI Application. Dê um nome (por exemplo Acme Copilot) e crie-a.
  2. Abra a aplicação. Seu App ID (vk_app_...) é exibido sob o nome do app e na URL da página. Copie-o para appId.
  3. Vá para a aba App Keys e clique em New Key. Selecione as permissões que seu backend precisa e, em seguida, Create Key.
  4. A Application Key (vk_app_sk_...) é exibida uma única vez, em um diálogo "Copy this key now". Copie-a para apiKey. Ela não pode ser recuperada depois.

Você pode rotacionar ou revogar uma chave a qualquer momento na mesma aba App Keys. Rotacionar invalida a chave antiga imediatamente e revela a nova uma única vez.

Mantenha vk_app_sk_... apenas no lado do servidor: em uma variável de ambiente ou no seu gerenciador de segredos. Nunca envie para um navegador, aplicativo móvel ou qualquer cliente controlado pelo usuário.

Instale o pacote

bash
npm install @vinkius/connect

Os comandos equivalentes são pnpm add @vinkius/connect, yarn add @vinkius/connect e bun add @vinkius/connect. O pacote é distribuído em ESM + CommonJS duplo, com tipos TypeScript embutidos, e não tem nenhuma dependência de runtime.

Configure as variáveis de ambiente do servidor

bash
VINKIUS_APP_ID=vk_app_xxxxxxxxxxxxxxxx
VINKIUS_APP_KEY=vk_app_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Crie um módulo exclusivo do servidor

typescript
// lib/vinkius.ts — import this module only from server code
import { Vinkius } from '@vinkius/connect';

function required(name: 'VINKIUS_APP_ID' | 'VINKIUS_APP_KEY'): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

export const vinkius = new Vinkius({
  appId: required('VINKIUS_APP_ID'),
  apiKey: required('VINKIUS_APP_KEY'),
});

O construtor verifica os prefixos do App ID e da chave, interpreta baseUrl quando fornecida e exige uma implementação de fetch. Ele não faz nenhuma requisição. Ele não executa validação de faixa em runtime para todo número opcional ou callback; portanto, mantenha timeoutMs, maxRetries, hooks e funções de nomenclatura personalizadas sob o controle da aplicação.

Se o seu runtime não tiver um fetch global, passe uma implementação compatível:

typescript
const vinkius = new Vinkius({
  appId,
  apiKey,
  fetch: customFetch,
});

Opções do cliente

typescript
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 }) => {},
  },
});

Verifique as credenciais com uma requisição

Uma verificação apenas de handles não entra em contato com a API. Use uma leitura do catálogo como teste de fumaça real:

typescript
import { VinkiusError } from '@vinkius/connect';
import { vinkius } from './lib/vinkius';

async function checkVinkiusConnection(): Promise<void> {
  try {
    const page = await vinkius.catalog.list({ page: 1 });
    console.log(`Vinkius API reachable; received ${page.data.length} connectors`);
  } catch (error: unknown) {
    if (error instanceof VinkiusError) {
      console.error({
        code: error.code,
        status: error.status,
        requestId: error.requestId,
      });
    }
    throw error;
  }
}

await checkVinkiusConnection();

Essa verificação confirma que o runtime consegue alcançar a API e que as credenciais da aplicação são aceitas. Um ConfigError local ocorre antes de qualquer requisição; AuthError representa uma resposta HTTP 401 ou 403.

Crie um handle de usuário

typescript
const user = vinkius.user('alice_123');

user() não faz nenhuma requisição. O ID deve ser o identificador estável do usuário na sua aplicação: de 1 a 255 caracteres, sem começar com vk_app_user_ e sem espaços em branco, barras ou barras invertidas.

user.ensure(metadata) é opcional. Chame-o quando precisar de um upsert explícito na API ou quiser anexar metadados não secretos, e não apenas para obter um handle.

Próximos passos