Inicio Rápido

Este inicio rápido conecta una cuenta de GitHub para un usuario de la aplicación, almacena las credenciales del conector, descubre las acciones disponibles para ese usuario y ejecuta una acción. El mismo flujo funciona con otros conectores; sus campos de credenciales y capacidades provienen de la API.

Requisitos previos

• Node.js 18 o posterior, o un entorno de ejecución de servidor con fetch
• @vinkius/connect instalado (consulta Installation)
• Un App ID y una Application Key de Vinkius en las variables de entorno del servidor
• Un token de GitHub para el conector del ejemplo

Inicio rápido completo

1. Crea un cliente reutilizable

import { Vinkius } from '@vinkius/connect';

const vinkius = new Vinkius({
  appId: process.env.VINKIUS_APP_ID!,
  apiKey: process.env.VINKIUS_APP_KEY!,
});

La construcción valida los prefijos de las credenciales, la URL base y la disponibilidad de fetch. No realiza ninguna solicitud HTTP.

2. Crea identificadores de usuario y conector

const user = vinkius.user('alice_123');
const github = user.connector('github');

Ambas llamadas son diferidas. Conservan el ID de usuario confiable de la aplicación y el identificador del conector, pero no envían ninguna solicitud. user.ensure({ plan: 'pro' }) es opcional y solo se necesita cuando quieres que la API cree o actualice explícitamente el usuario, o que almacene metadatos no secretos.

3. Crea o recupera la conexión

const connection = await github.connect();
console.log(connection.id);

Esto envía una solicitud POST. La API de Vinkius la trata como una operación de obtener o crear para este usuario de la aplicación y este conector. Volver a llamar a connect() también envía una solicitud, pero devuelve la misma conexión lógica en lugar de crear un duplicado.

4. Almacena las credenciales del conector

const credentialState = await github.credentials.set({
  GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
});

console.log(credentialState.configured);

Esto envía una solicitud PUT para la conexión existente. La respuesta informa qué claves están configuradas; no devuelve los valores almacenados. Para un conector cuyos campos no conoces, llama a await github.credentials.schema() antes de conectarlo. La consulta del esquema lee el catálogo y no requiere una conexión.

5. Carga las capacidades de este usuario

const capabilities = await user.capabilities({ include: ['github'] });
const createIssue = capabilities.findCapability('github__create_issue');

if (!createIssue) {
  throw new Error('GitHub create_issue is not available for this user');
}

Esto envía una solicitud GET. include se envía al servidor, por lo que la respuesta queda restringida a GitHub. Un conjunto vacío es válido; por ejemplo, cuando el conector no está listo o no expone acciones coincidentes.

6. Ejecuta la acción

const operationId = 'issue-request-123';
const result = await createIssue.execute(
  {
    owner: 'acme',
    repo: 'product',
    title: 'Document the release process',
  },
  { idempotencyKey: `create-issue:${operationId}` },
);

const text = result.content.map((part) => part.text).join('\n');
if (result.isError) {
  console.error('The connector reported a failed action:', text);
} else {
  console.log('Issue created:', text);
}

La ejecución envía una solicitud POST. La clave de idempotencia estable y no vacía permite que el SDK reintente fallos transitorios sin representar la misma acción lógica como una operación nueva. El SDK no valida que la clave no esté vacía; genérala y aplica esa restricción en tu aplicación.

Resumen de solicitudes

Una ejecución resuelta con isError: true es un resultado del conector. Los fallos de autenticación, HTTP, tiempo de espera y transporte normalmente lanzan en cambio una subclase de VinkiusError. Consulta Error handling.

Próximos pasos

• Build a connector form from its schema
• Convert capabilities for a model runtime
• Handle result and request failures