Documentation

AI Connect/Get started/Installation

Installation

Demandez à l’IA à propos de Vinkius

Ajoutez @vinkius/connect à un environnement d’exécution serveur, configurez les identifiants de l’application et vérifiez la connexion à l’API.

Installez le paquet dans votre backend et créez une instance Vinkius réutilisable. Le client enregistre la configuration au niveau de l’application, et non l’état propre à chaque utilisateur ; une même instance peut donc traiter les requêtes de nombreux utilisateurs.

Prérequis

  • Node.js 18 ou version ultérieure, ou un autre environnement d’exécution serveur qui fournit fetch (Node 18+, Bun, Deno et environnements d’exécution edge)
  • Un App ID Vinkius commençant par vk_app_
  • Une Application Key Vinkius commençant par vk_app_sk_

Obtenez vos identifiants d’API

Vinkius Connect s’authentifie avec deux valeurs provenant d’une Application Vinkius Cloud :

ValeurPréfixeDescription
appIdvk_app_...L’identifiant public de l’Application, qui identifie votre tenant
apiKeyvk_app_sk_...Une Application Key : le secret que votre backend utilise pour agir au nom de ses utilisateurs

Pour les créer dans le tableau de bord Vinkius Cloud :

  1. Ouvrez Build AI Apps (/ai-agents) et cliquez sur New AI Application. Donnez-lui un nom (par exemple Acme Copilot) et créez-la.
  2. Ouvrez l’application. Votre App ID (vk_app_...) est affiché sous le nom de l’application et dans l’URL de la page. Copiez-le dans appId.
  3. Accédez à l’onglet App Keys et cliquez sur New Key. Sélectionnez les permissions dont votre backend a besoin, puis Create Key.
  4. La Application Key (vk_app_sk_...) est affichée une seule fois, dans une boîte de dialogue "Copy this key now". Copiez-la dans apiKey. Elle ne pourra pas être récupérée ensuite.

Vous pouvez faire pivoter ou révoquer une clé à tout moment depuis le même onglet App Keys. La rotation invalide immédiatement l’ancienne clé et révèle la nouvelle une seule fois.

Conservez vk_app_sk_... côté serveur uniquement : dans une variable d’environnement ou votre gestionnaire de secrets. Ne l’expédiez jamais dans un navigateur, une application mobile ou tout client contrôlé par l’utilisateur.

Installer le paquet

bash
npm install @vinkius/connect

Les commandes équivalentes sont pnpm add @vinkius/connect, yarn add @vinkius/connect et bun add @vinkius/connect. Le paquet est livré en double format ESM + CommonJS avec les types TypeScript inclus et n’a aucune dépendance d’exécution.

Configurer les variables d’environnement du serveur

bash
VINKIUS_APP_ID=vk_app_xxxxxxxxxxxxxxxx
VINKIUS_APP_KEY=vk_app_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Créer un module réservé au serveur

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'),
});

Le constructeur vérifie les préfixes de l’App ID et de la clé, analyse baseUrl lorsqu’elle est fournie et exige une implémentation de fetch. Il n’effectue aucune requête. Il ne vérifie pas à l’exécution la plage de chaque nombre facultatif ni chaque callback ; gardez donc timeoutMs, maxRetries, les hooks et les fonctions de nommage personnalisées sous le contrôle de l’application.

Si votre environnement d’exécution ne possède pas de fetch global, transmettez une implémentation compatible :

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

Options du client

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

Vérifier les identifiants au moyen d’une requête

Une vérification limitée à un objet intermédiaire ne contacte pas l’API. Utilisez une lecture du catalogue pour un véritable test rapide :

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

Cette vérification confirme que l’environnement d’exécution peut joindre l’API et que les identifiants de l’application sont acceptés. Une ConfigError locale survient avant toute requête ; AuthError représente une réponse HTTP 401 ou 403.

Créer un objet utilisateur

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

user() n’effectue aucune requête. L’identifiant doit être l’identifiant utilisateur stable de votre application : de 1 à 255 caractères, sans commencer par vk_app_user_ et sans espace, barre oblique ni barre oblique inverse.

user.ensure(metadata) est facultatif. Appelez cette méthode lorsque vous avez besoin d’une création ou mise à jour explicite par l’API, ou souhaitez joindre des métadonnées non secrètes, et non simplement pour obtenir un objet intermédiaire.

Étapes suivantes