Documentación

AI Connect/Get started/Instalación

Instalación

Pregunta a la IA sobre Vinkius

Añade @vinkius/connect a un entorno de ejecución de servidor, configura las credenciales de la aplicación y verifica la conexión con la API.

Instala el paquete en tu backend y crea una única instancia reutilizable de Vinkius. El cliente almacena la configuración de la aplicación, no el estado de cada usuario, por lo que una misma instancia puede atender solicitudes de muchos usuarios.

Requisitos previos

  • Node.js 18 o posterior, u otro entorno de ejecución de servidor que proporcione fetch (Node 18+, Bun, Deno y entornos de ejecución en el edge)
  • Un App ID de Vinkius que comience por vk_app_
  • Una Application Key de Vinkius que comience por vk_app_sk_

Obtén tus credenciales de API

Vinkius Connect se autentica con dos valores de una Application de Vinkius Cloud:

ValorPrefijoQué es
appIdvk_app_...El id público de la Application, que identifica tu tenant
apiKeyvk_app_sk_...Una Application Key: el secreto que tu backend usa para actuar en nombre de sus usuarios

Para crearlos en el panel de Vinkius Cloud:

  1. Abre Build AI Apps (/ai-agents) y haz clic en New AI Application. Ponle un nombre (por ejemplo Acme Copilot) y créala.
  2. Abre la aplicación. Tu App ID (vk_app_...) se muestra bajo el nombre de la app y en la URL de la página. Cópialo en appId.
  3. Ve a la pestaña App Keys y haz clic en New Key. Selecciona los permisos que tu backend necesita y, a continuación, Create Key.
  4. La Application Key (vk_app_sk_...) se muestra una sola vez, en un diálogo "Copy this key now". Cópiala en apiKey. No podrá recuperarse después.

Puedes rotar o revocar una clave en cualquier momento desde la misma pestaña App Keys. Rotar invalida la clave antigua de inmediato y revela la nueva una sola vez.

Mantén vk_app_sk_... solo en el lado del servidor: en una variable de entorno o en tu gestor de secretos. Nunca la envíes a un navegador, una app móvil ni a ningún cliente que controle el usuario.

Instala el paquete

bash
npm install @vinkius/connect

Los comandos equivalentes son pnpm add @vinkius/connect, yarn add @vinkius/connect y bun add @vinkius/connect. El paquete se distribuye en formato dual ESM + CommonJS con tipos de TypeScript incluidos y no tiene dependencias en tiempo de ejecución.

Configura las variables de entorno del servidor

bash
VINKIUS_APP_ID=vk_app_xxxxxxxxxxxxxxxx
VINKIUS_APP_KEY=vk_app_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Crea un módulo exclusivo del 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'),
});

El constructor comprueba los prefijos del App ID y de la clave, analiza baseUrl cuando se proporciona y requiere una implementación de fetch. No realiza ninguna solicitud. No valida en tiempo de ejecución el rango de cada número o callback opcionales, por lo que debes mantener timeoutMs, maxRetries, los hooks y las funciones de nomenclatura personalizadas bajo el control de la aplicación.

Si tu entorno de ejecución no tiene un fetch global, proporciona una implementación compatible:

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

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

Verifica las credenciales con una solicitud

Una comprobación que solo crea un identificador no contacta con la API. Usa una lectura del catálogo para realizar una prueba de humo 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();

Esta comprobación verifica que el entorno de ejecución pueda acceder a la API y que se acepten las credenciales de la aplicación. Un ConfigError local ocurre antes de cualquier solicitud; AuthError representa una respuesta HTTP 401 o 403.

Crea un identificador de usuario

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

user() no realiza ninguna solicitud. El ID debe ser el identificador estable del usuario en tu aplicación: entre 1 y 255 caracteres, sin comenzar por vk_app_user_ y sin espacios en blanco, barras ni barras invertidas.

user.ensure(metadata) es opcional. Llámalo cuando necesites una creación o actualización explícita mediante la API, o cuando quieras adjuntar metadatos no secretos; no lo llames solo para obtener un identificador.

Próximos pasos