Connectors und Zugangsdaten

Ein Konnektor beschreibt eine Integration im Katalog. Eine Verbindung ist dieser Konnektor, konfiguriert für einen Anwendungsbenutzer. Diese Seite baut einen serverseitigen Einrichtungsfluss auf, ohne Feldnamen von Anmeldedaten anzunehmen.

Das SDK hat kein gehostetes Formular für Anmeldedaten und keine OAuth-UI-API. Ihre Anwendung rendert und autorisiert die Einrichtung und ruft dann die Konnektor-Methoden aus ihrem Backend auf.

Erstellen Sie ein lazies Konnektor-Handle

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

Keine der beiden Zeilen sendet eine Anfrage. Das Handle behält den Benutzerkontext und den Slug für spätere Operationen bei. Konnektor-Slugs werden unverändert an die API weitergegeben; anders als bei externalId wendet der Konstruktor keinen eigenen Slug-Validator an.

Lesen Sie die erforderlichen Felder für Anmeldedaten

const schema = await github.credentials.schema();

for (const [key, field] of Object.entries(schema)) {
  console.log(key, field.type, field.required ?? false);
}

schema() liest Katalogdetails und funktioniert, bevor eine Verbindung existiert. Ein Feld kann type-, label-, required-, group-, docs_url-, placeholder- und allowed-Werte enthalten. Verwenden Sie diese Deskriptoren, um Ihr eigenes Formular zu erstellen oder zu validieren.

Erstellen Sie die Verbindung und speichern Sie die Werte

async function configureConnector(
  externalId: string,
  slug: string,
  values: Record<string, string>,
) {
  const connector = vinkius.user(externalId).connector(slug);

  const connection = await connector.connect();
  const credentialState = await connector.credentials.set(values);
  const status = await connector.status();

  return {
    connectionId: connection.id,
    configured: credentialState.configured,
    status,
  };
}

connect() führt eine Anfrage aus. Nach dem API-Vertrag von Vinkius ist sie get-or-create für den Benutzer und den Konnektor, daher markiert das SDK die Operation als idempotent für vorübergehende Wiederholungsversuche. Ein wiederholter Aufruf führt dennoch Netzwerk-E/A aus.

Das Handle merkt sich die zurückgegebene Verbindungs-ID. Nachfolgende Aufrufe von credentials.set(), credentials.status() oder konnektorbezogenen capabilities() auf demselben Handle können sie ohne erneute Abfrage verwenden.

Interpretieren Sie den Konnektor-Status

const status = await github.status();

status() listet Verbindungen auf und gibt not_connected zurück, statt eine Ausnahme zu werfen, wenn keine existiert. credentials.status(), credentials.set(), disconnect() und konnektorbezogene capabilities() erfordern eine Verbindung und können ConnectorNotConnectedError auslösen.

Werte von Anmeldedaten sind nur schreibbar

const state = await github.credentials.status();

console.log(state.schema);
console.log(state.configured); // key -> boolean

Die API gibt das Schema und die Flags der konfigurierten Schlüssel zurück, nicht die gespeicherten Werte. Verwenden Sie den Status nicht, um Anmeldedaten abzurufen oder zu kopieren. Der Dienst prüft die übermittelten Werte gegen das Schema des Konnektors.

Listen Sie alle bestehenden Verbindungen auf

const summaries = await user.connectors();

for (const summary of summaries) {
  console.log(summary.slug, summary.status, summary.connectionId);
}

Diese Liste enthält nur bestehende Verbindungen und leitet dieselben vier Statuswerte aus jeder Verbindungsantwort ab.

Laden Sie Aktionen oder trennen Sie die Verbindung

const capabilities = await github.capabilities();
// Use or convert capabilities here.

await github.disconnect();

disconnect() löst die Verbindungs-ID auf, löscht die Verbindung und leert nach dem Erfolg den gespeicherten Wert dieses Handles. Ein anderes Handle hat einen eigenen gespeicherten Wert. Wenn eine Verbindung außerhalb eines Handles geändert wird, kann eine zuvor gespeicherte ID veraltet sein.

Entdecken Sie Konnektoren im Katalog

const page = await vinkius.catalog.list({ page: 1 });
const detail = await vinkius.catalog.get('github');

console.log(page.data);
console.log(detail.credential_schema);

catalog.search(query) sendet q an denselben Katalog-Endpunkt. Die Filterung hängt von der Unterstützung durch den Dienst ab; ein Dienst, der q ignoriert, kann die ungefilterte Liste zurückgeben.

Nächste Schritte

• Bind connector setup to authenticated users
• Select and execute capabilities
• Handle authentication and validation errors