Schnellstart

Dieser Schnellstart verbindet ein GitHub-Konto für einen Anwendungsbenutzer, speichert die Connector-Credentials, ermittelt die für diesen Benutzer verfügbaren Aktionen und führt eine Aktion aus. Derselbe Ablauf funktioniert auch für andere Connectors; deren Credential-Felder und Capabilities kommen aus der API.

Voraussetzungen

• Node.js 18 oder höher, oder eine Server-Laufzeitumgebung mit fetch
• @vinkius/connect installiert (siehe Installation)
• Eine Vinkius App ID und ein Application Key in Server-Umgebungsvariablen
• Ein GitHub-Token für den Beispiel-Connector

Vollständiger Schnellstart

1. Einen wiederverwendbaren Client erstellen

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

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

Die Konstruktion validiert die Präfixe der Credentials, die Basis-URL und die Verfügbarkeit von fetch. Es wird keine HTTP-Anfrage gesendet.

2. Benutzer- und Connector-Handles erstellen

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

Beide Aufrufe sind lazy. Sie halten die vertrauenswürdige Anwendungsbenutzer-ID und den Connector-Slug fest, senden aber keine Anfrage. user.ensure({ plan: 'pro' }) ist optional und nur dann nötig, wenn Sie die API den Benutzer explizit per Upsert anlegen oder nicht vertrauliche Metadaten speichern lassen möchten.

3. Die Verbindung erstellen oder abrufen

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

Dies sendet eine POST-Anfrage. Die Vinkius API behandelt sie als get-or-create für diesen Anwendungsbenutzer und Connector. Ein erneuter Aufruf von connect() sendet weiterhin eine Anfrage, gibt aber dieselbe logische Verbindung zurück, statt ein Duplikat zu erstellen.

4. Die Connector-Credentials speichern

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

console.log(credentialState.configured);

Dies sendet eine PUT-Anfrage für die bestehende Verbindung. Die Antwort meldet, welche Schlüssel konfiguriert sind; sie gibt keine gespeicherten Werte zurück. Wenn Sie die Felder eines Connectors nicht kennen, rufen Sie await github.credentials.schema() auf, bevor Sie die Verbindung herstellen. Das Schema-Lookup liest den Katalog und erfordert keine Verbindung.

5. Capabilities für diesen Benutzer laden

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

Dies sendet eine GET-Anfrage. include wird an den Server gesendet, daher ist die Antwort auf GitHub beschränkt. Ein leeres Set ist gültig, etwa wenn der Connector nicht bereit ist oder keine passenden Aktionen bereitstellt.

6. Die Aktion ausführen

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

Die Ausführung sendet eine POST-Anfrage. Der nicht leere, stabile Idempotency-Schlüssel erlaubt dem SDK, vorübergehende Fehler zu wiederholen, ohne dieselbe logische Aktion als neue Operation darzustellen. Das SDK prüft nicht, ob der Schlüssel nicht leer ist; erzeugen und durchsetzen Sie ihn in Ihrer Anwendung.

Übersicht der Anfragen

Eine abgeschlossene Ausführung mit isError: true ist ein Ergebnis auf Connector-Ebene. Authentifizierungs-, HTTP-, Timeout- und Transportfehler werfen stattdessen normalerweise eine VinkiusError-Unterklasse. Siehe Error handling.

Nächste Schritte

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