Référence de l’API

Vinkius est le point d’entrée limité à l’application. Utilisez ses handles fluents pour les flux d’utilisateurs, de connecteurs, d’identifiants et de capacités. Utilisez les clients de bas niveau lorsque vous avez besoin d’opérations directes sur les ressources.

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 du package

Package racine

Importez ces valeurs depuis @vinkius/connect :

La racine exporte également les types suivants :

HttpClient, les mécanismes internes de nouvelle tentative, les fonctions d’expurgation et les fonctions partagées entre adaptateurs ne sont pas exportés à la racine. Bien que les classes de clients de bas niveau soient exportées, leur constructeur exige le type interne HttpClient. Obtenez des instances au moyen de vinkius.catalog, vinkius.users et des fabriques limitées au contexte décrites ci-dessous.

Sous-chemins du package

Le package publie des points d’entrée ESM et CommonJS, ne déclare aucun effet de bord et exige Node.js 18 ou version ultérieure.

Créer un client

new Vinkius(options: VinkiusOptions)

Les requêtes comprennent Authorization: Bearer <apiKey>, x-vinkius-app-id, Accept: application/json et le user agent du SDK. Les requêtes avec un corps comprennent également Content-Type: application/json.

Créer un handle utilisateur paresseux

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

user() n’effectue aucune requête. externalId doit être l’ID utilisateur stable de votre application, et non un ID interne Vinkius commençant par vk_app_user_. Il doit comporter de 1 à 255 caractères et ne peut contenir ni espace, ni /, ni barre oblique inverse. Les valeurs invalides lèvent ConfigError.

Options de requête

La plupart des méthodes qui effectuent une requête acceptent RequestOptions. L’exécution d’une capacité accepte ExecuteOptions.

interface RequestOptions {
  signal?: AbortSignal;
}

interface ExecuteOptions extends RequestOptions {
  idempotencyKey?: string;
}

UserContext.ensure(metadata?) constitue l’exception : elle n’accepte pas RequestOptions. Les fonctions utilitaires de dispatch des adaptateurs et les callbacks générés par les adaptateurs n’acceptent pas non plus ExecuteOptions.

Utilisez une idempotencyKey stable et non vide pour une même exécution logique de capacité, et réutilisez-la uniquement lorsque vous répétez manuellement cette même opération.

API fluente

Résolution paresseuse

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

Ces instructions n’effectuent aucune requête. Un Connector ne résout sa connexion que lorsqu’une opération en a besoin, en comparant connection.slug ou connection.id au slug du handle. L’ID de connexion résolu est mémorisé uniquement sur ce handle. connect() stocke l’ID de connexion renvoyé ; disconnect() l’efface après la suppression.

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() effectue la création ou mise à jour idempotente de l’utilisateur ; le simple appel à user() ne crée aucun utilisateur. connectors() renvoie uniquement les connexions existantes ({ slug, status, connectionId? }).

Un tableau include non vide dans capabilities() est envoyé au serveur sous la forme d’une seule valeur de requête connector, séparée par des virgules ; un tableau exclude non vide est appliqué côté client après la réponse. Les capacités renvoyées sont exécutables et contiennent le connecteur et l’ID de connexion fournis par l’endpoint agrégé.

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() peut explicitement être réessayée sans risque et mémorise l’ID de connexion renvoyé. status() renvoie not_connected au lieu de lever une exception lorsqu’aucune connexion n’existe. disconnect() et capabilities() exigent une connexion et lèvent ConnectorNotConnectedError lorsque la résolution n’en trouve aucune.

ConnectorStatus est dérivé de la manière suivante :

CredentialsHandle

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

schema() lit l’entrée du catalogue et n’exige aucune connexion existante. status() et set() n’établissent jamais de connexion implicitement : elles commencent par résoudre une connexion existante et lèvent ConnectorNotConnectedError lorsqu’il n’en existe aucune.

Les valeurs d’identifiants sont en écriture seule. Les réponses relatives aux identifiants contiennent un schéma et des booléens pour les clés configurées, jamais les valeurs des identifiants :

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

La méthode fluente set() accepte un enregistrement plat et l’encapsule dans l’enveloppe de bas niveau { credentials: values }. Le client ne valide pas les valeurs par rapport au schéma avant de les envoyer.

Capacités

CapabilitySet

CapabilitySet étend Array<Capability>. Les méthodes de tableau standard sont disponibles.

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

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

forConnector() utilise une correspondance exacte sur le slug du connecteur. findCapability() renvoie la première correspondance exacte avec le nom d’affichage doté d’un espace de noms ou avec le nom brut du connecteur. Les noms bruts peuvent entrer en collision entre les connecteurs ; préférez les noms d’affichage, ou limitez d’abord le contexte :

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>;
}

L’exécution est toujours routée avec connectionId et rawName, et non avec le nom d’affichage. Capability est exportée, mais l’interface d’initialisation de son constructeur n’est pas exportée par le package : considérez les capacités comme des objets produits par le SDK au lieu de les construire manuellement.

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

isError: true est un résultat de capacité renvoyé, et non une exception levée. Les échecs HTTP, de transport, de configuration, de résolution de connecteur et de dispatch d’adaptateur peuvent toujours lever une exception.

Clients bas niveau

Utilisez les instances et fabriques exposées :

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

Les appels de fabrique n’effectuent aucune requête. Les méthodes de bas niveau renvoient des ressources ou des formes brutes de capacité plutôt que des handles fluents, sauf indication contraire.

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() utilise une pagination par page. get() accepte un slug de connecteur ou un ID de catalogue et renvoie credential_schema. search() envoie q et renvoie le tableau de données normalisé ; le filtrage dépend de la prise en charge de q par le serveur.

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() est une création ou mise à jour explicitement répétable par ID externe. capabilities() renvoie des CapabilityData[] brutes, et non des objets Capability exécutables ; utilisez user.capabilities() pour obtenir la forme fluente exécutable.

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() est une opération de récupération ou création explicitement répétable. list() renvoie un simple tableau.

CredentialsClient

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

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

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

La méthode de bas niveau exige l’enveloppe que le handle fluent ajoute pour vous :

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 est le nom brut de la capacité du connecteur. Il s’agit de la seule méthode de bas niveau qui accepte ExecuteOptions.

Types d’entrée et de ressource

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;
}

Les endpoints qui renvoient une liste simple acceptent soit un tableau nu, soit un objet avec data ; les formes inattendues sont normalisées en tableau vide. Les endpoints paginés attendent { data, meta?, links? }, normalisent un champ data absent ou qui n’est pas un tableau en tableau vide, et conservent les valeurs truthy de meta et links.

Hooks et expurgation

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

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

Les hooks s’exécutent de manière synchrone et ne sont pas attendus ; si un hook lève une exception, celle-ci est propagée et interrompt le flux de la requête.

Hook de requête. onRequest s’exécute avant chaque tentative avec l’URL complète de la requête et une copie de l’enregistrement des en-têtes. Il ne reçoit pas le corps de la requête, et les URL ne font pas l’objet d’une expurgation. Les noms des en-têtes sont comparés exactement, sans tenir compte de la casse ; les valeurs suivantes deviennent [REDACTED] : authorization, idempotency-key, cookie, set-cookie. Aucun autre en-tête n’est expurgé de manière heuristique.

Hook de réponse. onResponse s’exécute pour chaque tentative qui renvoie une réponse HTTP, y compris une réponse transitoire qui sera réessayée. Il ne s’exécute pas après une erreur de fetch ou un timeout sans réponse. Un corps vide vaut undefined ; le JSON valide est analysé ; le texte qui n’est pas du JSON reste une chaîne. Les clés de l’objet de réponse sont comparées exactement, sans tenir compte de la casse ; les valeurs suivantes deviennent [REDACTED] : authorization, apikey, api_key, token, access_token, refresh_token, mcp_url, credentials, password, secret, client_secret. Il n’existe aucune détection de secrets fondée sur des sous-chaînes ou sur la forme. Les objets à la profondeur 6 deviennent [TRUNCATED] ; les références répétées ou circulaires deviennent [CIRCULAR]. L’expurgation crée une copie destinée aux hooks et ne réécrit pas VinkiusError.details.

Timeouts, nouvelles tentatives et idempotence

Portée du timeout. Chaque tentative reçoit un nouveau timer timeoutMs couvrant la promesse fetch. Il est supprimé avant la lecture du corps de la réponse et ne couvre ni response.text() ni le délai entre les nouvelles tentatives ; les nouvelles tentatives ne partagent donc pas une échéance totale unique. Transmettez signal pour une annulation contrôlée par l’appelant : un abandon par l’appelant pendant fetch n’est pas réessayé et devient normalement ConnectionError.

Politique de nouvelles tentatives. Avec les valeurs par défaut, une opération pouvant être réessayée sans risque effectue au maximum trois tentatives. Une opération peut être réessayée sans risque lorsque sa méthode HTTP est GET, PUT ou DELETE, ou lorsque le SDK la marque explicitement comme telle : création d’utilisateur, création de connexion ou exécution de capacité avec une idempotencyKey définie. Ces opérations sont réessayées après une erreur réseau, un timeout propre à la tentative ou une réponse HTTP 429, 502, 503 ou 504. Les requêtes PATCH et POST ordinaires ne sont pas réessayées.

Le délai de reprise applique un jitter complet sur une fenêtre exponentielle : 250 ms au départ, avec un plafond de 4 000 ms. Retry-After (délai en secondes ou date HTTP) prend la priorité, toujours avec un plafond de 4 000 ms. maxRetries modifie le nombre de nouvelles tentatives, pas ces délais.

Erreurs et identifiants de requête

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

Les erreurs côté client et de transport utilisent l’état 0. Les échecs HTTP terminaux incluent la réponse analysée de l’API dans details.

Pour les réponses HTTP, le client lit le premier identifiant de requête non vide dans x-request-id, puis x-vinkius-request-id. La valeur est transmise à onResponse et jointe à l’erreur HTTP finale après conversion ; les valeurs de ressource réussies ne l’incluent pas. Les erreurs côté client et de transport ne possèdent normalement aucun identifiant de requête. Consultez Error handling pour les modèles de flux de contrôle.

ResolverCache

ResolverCache est un cache TTL autonome en mémoire pour les données stables et non secrètes. Le client ne l’utilise pas en interne.

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(),
);

Les entrées expirées sont supprimées lors de get(). resolve() calcule et stocke une valeur absente uniquement après la résolution de la promesse ; les rejets ne sont pas mis en cache et les recherches simultanées qui échouent ne sont pas regroupées. Une valeur undefined mise en cache ne peut pas être distinguée d’une absence. Ne mettez pas en cache des identifiants, des jetons, des en-têtes d’autorisation ou d’autres secrets : le cache est une optimisation, pas une source d’autorisation.

Référence des adaptateurs

Tous les adaptateurs acceptent readonly Capability[] et utilisent les noms d’affichage des capacités dans les définitions générées. Un schéma d’entrée vide est normalisé en { type: 'object', properties: {} }. Les adaptateurs ne valident pas localement les arguments des capacités ; la validation incombe au service appelé.

Les fonctions utilitaires de dispatch et les callbacks d’exécution générés appellent capability.execute(args) sans ExecuteOptions : ils ne peuvent recevoir ni signal ni clé d’idempotence. Appelez directement Capability.execute(args, options) ou ExecutionClient.execute(input, options) lorsque vous avez besoin d’une annulation ou d’une exécution pouvant être réessayée sans risque.

• toOpenAITools(capabilities) renvoie OpenAIFunctionTool[] ; runOpenAIToolCall(capabilities, call) compare uniquement le nom d’affichage. Une chaîne d’arguments JSON vide, mal formée, null ou primitive devient {} ; un nom inconnu lève une simple Error.
• toAnthropicTools / runAnthropicToolUse : comparaison uniquement par nom d’affichage ; les noms inconnus lèvent une simple Error.
• toAISDKTools(capabilities, { jsonSchema? }) renvoie un enregistrement indexé par nom d’affichage ; un nom d’affichage dupliqué remplace l’entrée précédente. Sans l’enveloppe injectée, parameters est le JSON Schema brut normalisé. Chaque execute(args) généré renvoie CapabilityResult.
• toGeminiTools / runGeminiFunctionCall : des arguments absents deviennent {} ; les noms inconnus lèvent une simple Error.
• toLangChainTools(capabilities, { tool }) et toOpenAIAgentsTools(capabilities, { tool }) exigent la fabrique de l’appelant et sont génériques par rapport à son type de retour. Les callbacks générés joignent les parties textuelles du résultat avec un saut de ligne et ne conservent ni isError ni le type des parties de contenu. L’adaptateur Agents transmet le JSON Schema brut normalisé avec strict: false.
• toLlamaIndexTools(capabilities, { tool }) accepte le JSON Schema brut, donc aucun Zod n’est requis.
• toWorkersAITools(capabilities) renvoie de simples objets dotés de fonctions d’exécution liées.
• toJSONSchemaTools(capabilities) émet { name, description, parameters } ; executeByName(capabilities, name, args) compare le nom d’affichage ou le nom brut, avec une ambiguïté de première correspondance pour les noms bruts dupliqués. Les noms inconnus lèvent une simple Error.

Étapes suivantes

• Comparez les framework adapters.
• Suivez les modèles de flux de contrôle d’error handling.
• Parcourez les recipes pour des modèles d’intégration ciblés.