Referencia de la API

Vinkius es el punto de entrada con alcance de aplicación. Usa sus handles fluidos para los flujos de usuarios, conectores, credenciales y capacidades. Usa los clientes de bajo nivel cuando necesites operaciones directas sobre recursos.

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

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

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

await github.connect();
await github.credentials.set({ GITHUB_TOKEN: process.env.GITHUB_TOKEN! });

const capabilities = await github.capabilities();

Exports del paquete

Paquete raíz

Importa estos valores desde @vinkius/connect:

El paquete raíz también exporta estos tipos:

HttpClient, los componentes internos de reintentos, los helpers de redacción y los helpers compartidos de los adaptadores no son exports del paquete raíz. Aunque las clases de clientes de bajo nivel se exportan, sus constructores requieren el tipo interno HttpClient. Obtén instancias mediante vinkius.catalog, vinkius.users y las fábricas con alcance descritas a continuación.

Subpaths del paquete

El paquete publica puntos de entrada ESM y CommonJS, declara que no tiene efectos secundarios y requiere Node.js 18 o posterior.

Crea un cliente

new Vinkius(options: VinkiusOptions)

Las solicitudes incluyen Authorization: Bearer <apiKey>, x-vinkius-app-id, Accept: application/json y el user agent del SDK. Las solicitudes con cuerpo también incluyen Content-Type: application/json.

Crea un handle de usuario perezoso

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

user() no realiza ninguna solicitud. externalId debe ser el ID de usuario estable de tu aplicación, no un ID interno de Vinkius que empiece por vk_app_user_. Debe contener entre 1 y 255 caracteres y no puede contener espacios en blanco, / ni barras invertidas. Los valores no válidos lanzan ConfigError.

Opciones de solicitud

La mayoría de los métodos que realizan solicitudes aceptan RequestOptions. La ejecución de capacidades acepta ExecuteOptions.

interface RequestOptions {
  signal?: AbortSignal;
}

interface ExecuteOptions extends RequestOptions {
  idempotencyKey?: string;
}

UserContext.ensure(metadata?) es la excepción: no acepta RequestOptions. Los helpers de despacho de los adaptadores y los callbacks generados por adaptadores tampoco aceptan ExecuteOptions.

Usa una idempotencyKey estable y no vacía para la misma ejecución lógica de una capacidad y reutilízala solo cuando repitas manualmente esa misma operación.

API fluida

Resolución perezosa

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

Estas instrucciones no realizan solicitudes. Un Connector solo resuelve su conexión cuando una operación la necesita, comparando connection.slug o connection.id con el slug del handle. El ID de conexión resuelto se memoiza únicamente en ese handle. connect() almacena el ID de conexión devuelto; disconnect() lo elimina después de borrar la conexión.

UserContext

class UserContext {
  readonly externalId: string;

  ensure(metadata?: Record<string, unknown>): Promise<AppUser>;
  get(options?: RequestOptions): Promise<AppUser>;
  connector(slug: string): Connector;
  connectors(options?: RequestOptions): Promise<ConnectorSummary[]>;
  capabilities(options?: CapabilityQuery): Promise<CapabilitySet>;
}

ensure() realiza el upsert idempotente del usuario; llamar solo a user() no crea un usuario. connectors() devuelve únicamente las conexiones existentes ({ slug, status, connectionId? }).

Un array include no vacío en capabilities() se envía al servidor como un único valor de consulta connector separado por comas; exclude se aplica en el cliente después de la respuesta. Las capacidades devueltas son ejecutables y contienen el conector y el ID de conexión proporcionados por el endpoint agregado.

Connector

class Connector {
  readonly slug: string;
  readonly credentials: CredentialsHandle;

  connect(options?: RequestOptions): Promise<Connection>;
  disconnect(options?: RequestOptions): Promise<void>;
  status(options?: RequestOptions): Promise<ConnectorStatus>;
  capabilities(options?: RequestOptions): Promise<CapabilitySet>;
}

connect() permite reintentos de forma explícitamente segura y memoiza el ID de conexión devuelto. status() devuelve not_connected en vez de lanzar una excepción cuando no existe una conexión. disconnect() y capabilities() requieren una conexión y lanzan ConnectorNotConnectedError cuando la resolución no encuentra ninguna.

ConnectorStatus se deriva de la siguiente forma:

CredentialsHandle

class CredentialsHandle {
  schema(options?: RequestOptions): Promise<CredentialSchema>;
  status(options?: RequestOptions): Promise<CredentialStatus>;
  set(
    values: Record<string, string>,
    options?: RequestOptions,
  ): Promise<CredentialStatus>;
}

schema() lee la entrada del catálogo y no requiere una conexión existente. status() y set() nunca conectan implícitamente: primero resuelven una conexión existente y lanzan ConnectorNotConnectedError cuando no hay ninguna.

Los valores de las credenciales son de solo escritura. Las respuestas de credenciales contienen un esquema y valores booleanos para las claves configuradas, nunca los valores de las credenciales:

interface CredentialStatus {
  schema: CredentialSchema;
  configured: Record<string, boolean>;
}

El método fluido set() acepta un mapa plano y lo envuelve en el objeto de bajo nivel { credentials: values }. El cliente no valida los valores con el esquema antes de enviarlos.

Capacidades

CapabilitySet

CapabilitySet extiende Array<Capability>. Están disponibles los métodos estándar de los arrays.

class CapabilitySet extends Array<Capability> {
  static fromCapabilities(
    capabilities: readonly Capability[],
  ): CapabilitySet;

  forConnector(slug: string): CapabilitySet;
  findCapability(name: string): Capability | undefined;
}

forConnector() usa una coincidencia exacta con el slug del conector. findCapability() devuelve la primera coincidencia exacta con el nombre de visualización con namespace o con el nombre del conector en bruto. Los nombres en bruto pueden colisionar entre conectores; prefiere los nombres de visualización o limita primero el alcance:

const issue = capabilities
  .forConnector('github')
  .findCapability('create_issue');

Capability

class Capability {
  readonly connector: string;
  readonly connectionId: string;
  readonly name: string;
  readonly rawName: string;
  readonly title: string | null;
  readonly description: string;
  readonly inputSchema: JSONSchema;

  execute(
    args?: Record<string, unknown>,
    options?: ExecuteOptions,
  ): Promise<CapabilityResult>;
}

La ejecución siempre se enruta con connectionId y rawName, no con el nombre de visualización. Capability se exporta, pero la interfaz de inicialización de su constructor no es un export del paquete: trata las capacidades como objetos producidos por el SDK en vez de construirlas manualmente.

interface CapabilityResult {
  content: Array<{ type: string; text: string }>;
  isError: boolean;
}

isError: true es un resultado de capacidad devuelto, no una excepción lanzada. Los fallos HTTP, de transporte, de configuración, de resolución del conector y de despacho del adaptador sí pueden lanzar excepciones.

Clientes de bajo nivel

Usa las instancias y fábricas expuestas:

const catalog = vinkius.catalog;
const users = vinkius.users;
const connections = users.connections('alice_123');
const credentials = connections.credentials(connectionId);
const execution = connections.execution(connectionId);

Las llamadas a fábricas no realizan solicitudes. Los métodos de bajo nivel devuelven recursos o formas de capacidad sin procesar, en lugar de handles fluidos, salvo que se indique lo contrario.

CatalogClient

class CatalogClient {
  list(
    options?: { page?: number } & RequestOptions,
  ): Promise<Paginated<CatalogConnector>>;

  get(
    slug: string,
    options?: RequestOptions,
  ): Promise<CatalogConnectorDetail>;

  search(
    query: string,
    options?: RequestOptions,
  ): Promise<CatalogConnector[]>;
}

list() usa paginación por páginas. get() acepta un slug de conector o un ID de catálogo y devuelve credential_schema. search() envía q y devuelve el array de datos normalizado; el filtrado depende de que el servidor admita q.

AppUsersClient

class AppUsersClient {
  create(
    input: CreateAppUserInput,
    options?: RequestOptions,
  ): Promise<AppUser>;

  get(externalId: string, options?: RequestOptions): Promise<AppUser>;

  update(
    externalId: string,
    patch: UpdateAppUserInput,
    options?: RequestOptions,
  ): Promise<AppUser>;

  delete(externalId: string, options?: RequestOptions): Promise<void>;

  list(
    options?: { status?: string; page?: number } & RequestOptions,
  ): Promise<Paginated<AppUser>>;

  capabilities(
    externalId: string,
    options?: { connectors?: string[] } & RequestOptions,
  ): Promise<CapabilityData[]>;

  connections(externalId: string): ConnectionsClient;
}

create() es un upsert por ID externo que permite reintentos de forma explícitamente segura. capabilities() devuelve CapabilityData[] sin procesar, no objetos Capability ejecutables; usa user.capabilities() para obtener la forma fluida ejecutable.

ConnectionsClient

class ConnectionsClient {
  list(options?: RequestOptions): Promise<Connection[]>;

  create(
    input: CreateConnectionInput,
    options?: RequestOptions,
  ): Promise<Connection>;

  get(
    connectionId: string,
    options?: RequestOptions,
  ): Promise<Connection>;

  delete(
    connectionId: string,
    options?: RequestOptions,
  ): Promise<void>;

  credentials(connectionId: string): CredentialsClient;
  execution(connectionId: string): ExecutionClient;
}

create() es una operación get-or-create que permite reintentos de forma explícitamente segura. list() devuelve un array simple.

CredentialsClient

class CredentialsClient {
  status(options?: RequestOptions): Promise<CredentialStatus>;

  set(
    input: SetCredentialsInput,
    options?: RequestOptions,
  ): Promise<CredentialStatus>;
}

interface SetCredentialsInput {
  credentials: Record<string, string>;
}

El método de bajo nivel requiere el objeto que el handle fluido añade por ti:

await connections.credentials(connection.id).set({
  credentials: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
});

ExecutionClient

class ExecutionClient {
  list(options?: RequestOptions): Promise<CapabilityData[]>;

  execute(
    input: ExecuteCapabilityInput,
    options?: ExecuteOptions,
  ): Promise<CapabilityResult>;
}

interface ExecuteCapabilityInput {
  name: string;
  arguments?: Record<string, unknown>;
}

name es el nombre en bruto de la capacidad del conector. Este es el único método de bajo nivel que acepta ExecuteOptions.

Tipos de entrada y recursos

interface CreateAppUserInput {
  external_id: string;
  status?: string;
  metadata?: Record<string, unknown>;
}

interface UpdateAppUserInput {
  status?: string;
  metadata?: Record<string, unknown>;
}

interface CreateConnectionInput {
  connector: string;
}

interface SetCredentialsInput {
  credentials: Record<string, string>;
}

interface ExecuteCapabilityInput {
  name: string;
  arguments?: Record<string, unknown>;
}

type ISODate = string;
type JSONSchema = Record<string, unknown>;

interface AppUser {
  id: string;
  external_id: string;
  status: string;
  metadata: Record<string, unknown> | null;
  application_id?: string;
  mcp_count?: number;
  created_at: ISODate;
  updated_at: ISODate;
}

interface Connection {
  id: string;
  slug: string | null;
  name: string;
  description: string | null;
  status: string;
  ready: boolean;
  tokens_count?: number;
  created_at: ISODate;
}

interface CatalogConnector {
  id: string;
  slug: string;
  title: string;
  short_description: string | null;
  publisher_type: string;
  listing_type: string;
  requires_buyer_auth: boolean;
  server_type?: string;
  tools_count?: number;
}

interface CatalogConnectorDetail extends CatalogConnector {
  credential_schema: CredentialSchema;
}

type CredentialType =
  | 'api_key'
  | 'token'
  | 'password'
  | 'connection_string'
  | 'string'
  | 'number'
  | 'email'
  | 'url'
  | 'select'
  | 'boolean'
  | 'oauth2';

interface CredentialField {
  type: CredentialType;
  label?: string;
  required?: boolean;
  group?: string;
  docs_url?: string;
  placeholder?: string;
  allowed?: string[];
}

type CredentialSchema = Record<string, CredentialField>;

interface CapabilityData {
  name: string;
  title?: string | null;
  description?: string | null;
  input_schema?: JSONSchema | null;
  annotations?: unknown;
  connector?: string;
  connection_id?: string;
}

interface Paginated<T> {
  data: T[];
  meta?: PageMeta;
  links?: PageLinks;
}

interface PageMeta {
  current_page: number;
  from: number | null;
  last_page: number;
  path: string;
  per_page: number;
  to: number | null;
  total: number;
}

interface PageLinks {
  first: string | null;
  last: string | null;
  prev: string | null;
  next: string | null;
}

Los endpoints de listas simples aceptan un array sin envolver o un objeto con data; las formas inesperadas se normalizan a un array vacío. Los endpoints paginados esperan { data, meta?, links? }, normalizan un campo data ausente o que no sea un array a un array vacío y conservan los valores truthy de meta y links.

Hooks y redacción

interface Hooks {
  onRequest?: (info: {
    method: string;
    url: string;
    headers: Record<string, string>;
  }) => void;

  onResponse?: (info: {
    status: number;
    url: string;
    requestId?: string;
    body: unknown;
  }) => void;
}

Los hooks se ejecutan de forma síncrona y no se esperan; si un hook lanza una excepción, esta se propaga y detiene el flujo de la solicitud.

Hook de solicitud. onRequest se ejecuta antes de cada intento con la URL completa de la solicitud y una copia del mapa de encabezados. No recibe el cuerpo de la solicitud, y las URL no se redactan. Los nombres de encabezados se comparan de forma exacta, sin distinguir mayúsculas y minúsculas; estos valores se convierten en [REDACTED]: authorization, idempotency-key, cookie, set-cookie. Ningún otro encabezado se redacta mediante heurísticas.

Hook de respuesta. onResponse se ejecuta en cada intento que devuelve una respuesta HTTP, incluida una respuesta transitoria que se reintentará. No se ejecuta ante un fallo de fetch o un timeout sin respuesta. Un cuerpo vacío es undefined; el JSON válido se analiza; el texto que no es JSON permanece como string. Las claves de los objetos de respuesta se comparan de forma exacta, sin distinguir mayúsculas y minúsculas; estos valores se convierten en [REDACTED]: authorization, apikey, api_key, token, access_token, refresh_token, mcp_url, credentials, password, secret, client_secret. No hay detección de secretos por substring ni por forma. Los objetos en la profundidad 6 se convierten en [TRUNCATED]; las referencias repetidas o circulares se convierten en [CIRCULAR]. La redacción crea una copia para los hooks y no reescribe VinkiusError.details.

Timeouts, reintentos e idempotencia

Alcance del timeout. Cada intento recibe un nuevo temporizador timeoutMs que cubre la promesa de fetch. Se borra antes de leer el cuerpo de la respuesta y no cubre response.text() ni la espera entre reintentos, por lo que los reintentos no comparten un único plazo límite total. Pasa signal para una cancelación controlada por el llamador: un aborto del llamador durante fetch no se reintenta y normalmente se convierte en ConnectionError.

Política de reintentos. Con los valores predeterminados, una operación que puede reintentarse de forma segura realiza como máximo tres intentos. Una operación puede reintentarse de forma segura cuando su método HTTP es GET, PUT o DELETE, o cuando el SDK la marca explícitamente como segura para reintentos: creación de usuario, creación de conexión o ejecución de una capacidad con una idempotencyKey definida. Las operaciones que permiten reintentos seguros se reintentan tras un error de red, un timeout por intento o un estado HTTP 429, 502, 503 o 504. Las solicitudes PATCH y POST ordinarias no se reintentan.

La espera usa full jitter sobre una ventana exponencial: 250 ms al principio, con un límite de 4.000 ms. Retry-After (segundos delta o una fecha HTTP) tiene prioridad, también con un límite de 4.000 ms. maxRetries cambia la cantidad de reintentos, no estos valores de espera.

Errores e identificadores de solicitud

class VinkiusError extends Error {
  readonly status: number;
  readonly code: VinkiusErrorCode;
  readonly requestId: string | undefined;
  readonly details: unknown;
}

Los errores del cliente y de transporte usan el estado 0. Los fallos HTTP terminales incluyen la respuesta de API analizada en details.

Para las respuestas HTTP, el cliente lee el primer ID de solicitud no vacío de x-request-id y, después, x-vinkius-request-id. El valor se pasa a onResponse y se adjunta al error HTTP final mapeado; los recursos devueltos con éxito no lo incluyen. Los errores del cliente y de transporte normalmente no tienen un ID de solicitud. Consulta Error handling para ver patrones de flujo de control.

ResolverCache

ResolverCache es una caché TTL en memoria e independiente para datos estables que no sean secretos. El cliente no la usa internamente.

class ResolverCache {
  constructor(ttlMs?: number); // Default: 5 minutes.

  get<V>(key: string): V | undefined;
  set<V>(key: string, value: V): void;
  delete(key: string): void;
  clear(): void;
  resolve<V>(key: string, compute: () => Promise<V>): Promise<V>;
}

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

const cache = new ResolverCache(10 * 60 * 1000);
const schema = await cache.resolve('github:schema', () =>
  user.connector('github').credentials.schema(),
);

Las entradas expiradas se eliminan al llamar a get(). resolve() calcula y almacena un valor ausente solo después de que la promesa se resuelva correctamente; los rechazos no se almacenan en caché y los misses simultáneos no se agrupan. Un undefined almacenado no se distingue de un miss. No almacenes en caché credenciales, tokens, encabezados de autorización ni otros secretos: la caché es una optimización, no una fuente de autorización.

Referencia de adaptadores

Todos los adaptadores aceptan readonly Capability[] y usan los nombres de visualización de las capacidades en las definiciones generadas. Un esquema de entrada vacío se normaliza a { type: 'object', properties: {} }. Los adaptadores no validan localmente los argumentos de las capacidades; la validación corresponde al servicio llamado.

Los helpers de despacho y los callbacks de ejecución generados llaman a capability.execute(args) sin ExecuteOptions: no pueden recibir una señal ni una clave de idempotencia. Llama directamente a Capability.execute(args, options) o ExecutionClient.execute(input, options) cuando necesites cancelación o una ejecución que permita reintentos seguros.

• toOpenAITools(capabilities) devuelve OpenAIFunctionTool[]; runOpenAIToolCall(capabilities, call) compara solo el nombre de visualización. Los strings de argumentos JSON vacíos, malformados, null o primitivos se convierten en {}; un nombre desconocido lanza un Error simple.
• toAnthropicTools / runAnthropicToolUse: comparación solo por nombre de visualización; los nombres desconocidos lanzan un Error simple.
• toAISDKTools(capabilities, { jsonSchema? }) devuelve un registro indexado por nombre de visualización; un nombre de visualización duplicado sobrescribe la entrada anterior. Sin el wrapper inyectado, parameters es el JSON Schema normalizado sin procesar. Cada execute(args) generado devuelve CapabilityResult.
• toGeminiTools / runGeminiFunctionCall: si faltan los argumentos, se usa {}; los nombres desconocidos lanzan un Error simple.
• toLangChainTools(capabilities, { tool }) y toOpenAIAgentsTools(capabilities, { tool }) requieren la fábrica del llamador y son genéricos respecto de su tipo de retorno. Los callbacks generados unen las partes de texto del resultado con un salto de línea y no conservan isError ni los tipos de las partes de contenido. El adaptador de Agents pasa el JSON Schema normalizado sin procesar con strict: false.
• toLlamaIndexTools(capabilities, { tool }) acepta JSON Schema sin procesar, por lo que no se requiere Zod.
• toWorkersAITools(capabilities) devuelve objetos simples con funciones de ejecución vinculadas.
• toJSONSchemaTools(capabilities) emite { name, description, parameters }; executeByName(capabilities, name, args) compara el nombre de visualización o el nombre en bruto, con ambigüedad de primera coincidencia para nombres en bruto duplicados. Los nombres desconocidos lanzan un Error simple.

Próximos pasos

• Compara los framework adapters.
• Sigue los patrones de flujo de control de error handling.
• Explora las recipes para ver patrones de integración enfocados.