API-Referenz

Vinkius ist der Einstiegspunkt auf Anwendungsebene. Verwenden Sie die fluiden Handles für Benutzer-, Connector-, Credential- und Capability-Workflows. Verwenden Sie die Low-Level-Clients, wenn Sie direkte Ressourcenoperationen benötigen.

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

Paket-Exporte

Stammpaket

Importieren Sie diese Werte aus @vinkius/connect:

Das Stammpaket exportiert außerdem diese Typen:

HttpClient, die internen Wiederholungsmechanismen, die Schwärzungs-Helfer und die von Adaptern gemeinsam genutzten Helfer sind keine Exporte des Stammpakets. Obwohl die Low-Level-Client-Klassen exportiert werden, verlangen ihre Konstruktoren den internen Typ HttpClient. Beziehen Sie Instanzen über vinkius.catalog, vinkius.users und die unten beschriebenen bereichsbezogenen Fabriken.

Paket-Subpaths

Das Paket veröffentlicht ESM- und CommonJS-Einstiegspunkte, deklariert keine Seiteneffekte und erfordert Node.js 18 oder höher.

Einen Client erstellen

new Vinkius(options: VinkiusOptions)

Anfragen enthalten Authorization: Bearer <apiKey>, x-vinkius-app-id, Accept: application/json und den User-Agent des SDK. Anfragen mit einem Körper enthalten zusätzlich Content-Type: application/json.

Ein lazy User-Handle erstellen

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

user() führt keine Anfrage aus. externalId muss die stabile Benutzer-ID Ihrer Anwendung sein, nicht eine interne Vinkius-ID, die mit vk_app_user_ beginnt. Er muss 1 bis 255 Zeichen enthalten und darf keine Leerzeichen, / oder umgekehrten Schrägstriche enthalten. Ungültige Werte werfen ConfigError.

Anfrageoptionen

Die meisten anfrageauslösenden Methoden akzeptieren RequestOptions. Die Capability-Ausführung akzeptiert ExecuteOptions.

interface RequestOptions {
  signal?: AbortSignal;
}

interface ExecuteOptions extends RequestOptions {
  idempotencyKey?: string;
}

UserContext.ensure(metadata?) ist die Ausnahme: Er akzeptiert kein RequestOptions. Die Dispatch-Helfer der Adapter und die von Adaptern erzeugten Callbacks akzeptieren ebenfalls kein ExecuteOptions.

Verwenden Sie einen nicht leeren, stabilen idempotencyKey für dieselbe logische Capability-Ausführung und verwenden Sie ihn nur erneut, wenn Sie genau diese Operation manuell wiederholen.

Fluide API

Lazy-Auflösung

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

Diese Anweisungen führen keine Anfragen aus. Ein Connector löst seine Verbindung erst auf, wenn eine Operation sie benötigt, und gleicht dabei connection.slug oder connection.id mit dem slug des Handles ab. Die aufgelöste Verbindungs-ID wird nur auf diesem Handle gemerkt. connect() speichert die zurückgegebene Verbindungs-ID; disconnect() löscht sie nach der Löschung.

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() führt das idempotente Benutzer-Upsert durch; der Aufruf von user() allein erstellt keinen Benutzer. connectors() gibt nur bestehende Verbindungen zurück ({ slug, status, connectionId? }).

Ein nicht leeres include-Array in capabilities() wird als ein einziger kommagetrennter connector-Abfragewert an den Server gesendet; exclude wird clientseitig nach der Antwort angewendet. Die zurückgegebenen Capabilities sind ausführbar und tragen den Connector und die Verbindungs-ID, die der aggregierte Endpoint liefert.

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() ist ausdrücklich wiederholsicher und merkt sich die zurückgegebene Verbindungs-ID. status() gibt not_connected zurück, statt zu werfen, wenn keine Verbindung existiert. disconnect() und capabilities() benötigen eine Verbindung und werfen ConnectorNotConnectedError, wenn die Auflösung keine findet.

ConnectorStatus wird wie folgt abgeleitet:

CredentialsHandle

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

schema() liest den Katalogeintrag und erfordert keine bestehende Verbindung. status() und set() verbinden nie implizit: Sie lösen zuerst eine bestehende Verbindung auf und werfen ConnectorNotConnectedError, wenn keine existiert.

Credential-Werte sind nur schreibbar. Credential-Antworten enthalten ein Schema und boolesche Werte für konfigurierte Schlüssel, niemals Credential-Werte:

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

Das fluide set() akzeptiert eine flache Map und verpackt sie in den Low-Level-Umschlag { credentials: values }. Der Client validiert die Werte vor dem Senden nicht gegen das Schema.

Capabilities

CapabilitySet

CapabilitySet erweitert Array<Capability>. Standard-Array-Methoden sind verfügbar.

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

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

forConnector() verwendet einen exakten Abgleich des Connector-Slugs. findCapability() gibt die erste exakte Übereinstimmung mit dem mit Namespace versehenen Anzeigenamen oder dem rohen Connector-Namen zurück. Rohe Namen können über Connectors hinweg kollidieren; bevorzugen Sie Anzeigenamen oder grenzen Sie zuerst den Geltungsbereich ein:

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

Die Ausführung wird immer mit connectionId und rawName geroutet, nicht mit dem Anzeigenamen. Capability wird exportiert, aber die Initialisierungsschnittstelle ihres Konstruktors ist kein Paketexport: Behandeln Sie Capabilities als vom SDK erzeugte Objekte, statt sie manuell zu konstruieren.

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

isError: true ist ein zurückgegebenes Capability-Ergebnis, keine geworfene Ausnahme. HTTP-, Transport-, Konfigurations-, Connector-Auflösungs- und Adapter-Dispatch-Fehler können weiterhin werfen.

Low-Level-Clients

Verwenden Sie die bereitgestellten Instanzen und Fabriken:

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

Fabrikaufrufe sind anfragefrei. Low-Level-Methoden geben Ressourcen- oder rohe Capability-Formen zurück, sofern nicht anders angegeben.

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() ist seitenbasiert. get() akzeptiert einen Connector-Slug oder eine Katalog-ID und gibt credential_schema zurück. search() sendet q und gibt das normalisierte Daten-Array zurück; die Filterung hängt von der Serverunterstützung für q ab.

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() ist ein ausdrücklich wiederholsicheres Upsert nach externer ID. capabilities() gibt rohe CapabilityData[] zurück, keine ausführbaren Capability-Objekte; verwenden Sie user.capabilities() für die fluide ausführbare Form.

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() ist eine ausdrücklich wiederholsichere Get-or-Create-Operation. list() gibt ein einfaches Array zurück.

CredentialsClient

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

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

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

Die Low-Level-Methode erfordert den Umschlag, den das fluide Handle für Sie hinzufügt:

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 ist der rohe Connector-Capability-Name. Dies ist die einzige Low-Level-Methode, die ExecuteOptions akzeptiert.

Eingabe- und Ressourcentypen

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

Endpoints mit einfachen Listen akzeptieren entweder ein nacktes Array oder ein Objekt mit data; unerwartete Formen werden zu einem leeren Array normalisiert. Paginierte Endpoints erwarten { data, meta?, links? }, normalisieren ein fehlendes oder nicht Array-förmiges data-Feld zu einem leeren Array und behalten truthy meta- und links-Werte bei.

Hooks und Schwärzung

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

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

Hooks laufen synchron und werden nicht abgewartet; wirft ein Hook eine Ausnahme, breitet sich diese aus und stoppt den Anfragefluss.

Request-Hook. onRequest läuft vor jedem Versuch mit der vollständigen Anfrage-URL und einer kopierten Header-Map. Er empfängt nicht den Anfragekörper, und URLs werden nicht geschwärzt. Header-Namen werden exakt und ohne Groß-/Kleinschreibung abgeglichen; diese Werte werden zu [REDACTED]: authorization, idempotency-key, cookie, set-cookie. Kein anderer Header wird heuristisch geschwärzt.

Response-Hook. onResponse läuft für jeden Versuch, der eine HTTP-Antwort zurückgibt, einschließlich einer vorübergehenden Antwort, die wiederholt wird. Er läuft nicht bei einem Fetch-Fehlschlag oder einem Timeout ohne Antwort. Ein leerer Körper ist undefined; gültiges JSON wird geparst; Nicht-JSON-Text bleibt ein String. Schlüssel des Response-Objekts werden exakt und ohne Groß-/Kleinschreibung abgeglichen; diese werden zu [REDACTED]: authorization, apikey, api_key, token, access_token, refresh_token, mcp_url, credentials, password, secret, client_secret. Es gibt keine substring- oder formenbasierte Geheimniserkennung. Objekte ab Tiefe 6 werden zu [TRUNCATED]; wiederholte oder zirkuläre Referenzen werden zu [CIRCULAR]. Die Schwärzung erstellt eine Kopie für die Hooks und schreibt VinkiusError.details nicht um.

Timeouts, Wiederholungen und Idempotenz

Timeout-Geltungsbereich. Jeder Versuch erhält einen neuen timeoutMs-Timer, der das fetch-Promise umfasst. Er wird vor dem Lesen des Antwortkörpers gelöscht und deckt weder response.text() noch den Wiederholungs-Backoff ab, sodass Wiederholungen keine gemeinsame Gesamtfrist teilen. Übergeben Sie signal für eine anrufergesteuerte Abbruchmöglichkeit: ein Abbruch des Anrufers während des Fetch wird nicht wiederholt und wird normalerweise zu ConnectionError.

Wiederholungsrichtlinie. Mit den Standardwerten führt eine wiederholsichere Operation höchstens drei Versuche aus. Eine Operation ist wiederholsicher, wenn ihre HTTP-Methode GET, PUT oder DELETE ist oder wenn das SDK sie ausdrücklich als wiederholsicher markiert: Benutzererstellung, Verbindungserstellung oder Capability-Ausführung mit definiertem idempotencyKey. Wiederholsichere Operationen werden nach einem Netzwerkfehler, einem Timeout pro Versuch oder HTTP 429, 502, 503 oder 504 wiederholt. PATCH- und gewöhnliche POST-Anfragen werden nicht wiederholt.

Der Backoff verwendet vollständiges Jitter über ein exponentielles Fenster: anfangs 250 ms, begrenzt auf 4.000 ms. Retry-After (Delta-Sekunden oder ein HTTP-Datum) hat Vorrang, ebenfalls begrenzt auf 4.000 ms. maxRetries ändert die Wiederholungsanzahl, nicht diese Verzögerungswerte.

Fehler und Anfrage-IDs

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

Clientseitige Fehler und Transportfehler verwenden den Status 0. Terminale HTTP-Fehlschläge enthalten die geparste API-Antwort in details.

Bei HTTP-Antworten liest der Client die erste nicht leere Anfrage-ID aus x-request-id und danach aus x-vinkius-request-id. Der Wert erreicht onResponse und den finalen zugeordneten HTTP-Fehler; erfolgreiche Ressourcenwerte enthalten ihn nicht. Clientseitige Fehler und Transportfehler haben normalerweise keine Anfrage-ID. Siehe Error handling für Kontrollflussmuster.

ResolverCache

ResolverCache ist ein eigenständiger In-Memory-TTL-Cache für nicht geheime, stabile Daten. Der Client verwendet ihn intern nicht.

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

Abgelaufene Einträge werden bei get() gelöscht. resolve() berechnet und speichert einen fehlenden Wert erst, nachdem das Promise erfüllt ist; Ablehnungen werden nicht gecacht, und gleichzeitige Fehlversuche werden nicht zusammengeführt. Ein gecachtes undefined ist von einem Fehlversuch nicht zu unterscheiden. Cachen Sie keine Credentials, Tokens, Authorization-Header oder andere Geheimnisse: Der Cache ist eine Optimierung, keine Autorisierungsquelle.

Adapter-Referenz

Alle Adapter akzeptieren readonly Capability[] und verwenden Capability-Anzeigenamen in den generierten Definitionen. Ein leeres Eingabeschema wird zu { type: 'object', properties: {} } normalisiert. Adapter validieren Capability-Argumente nicht lokal; die Validierung obliegt dem aufgerufenen Dienst.

Dispatch-Helfer und generierte Ausführungs-Callbacks rufen capability.execute(args) ohne ExecuteOptions auf: Sie können kein Signal und keinen Idempotenz-Schlüssel empfangen. Rufen Sie Capability.execute(args, options) oder ExecutionClient.execute(input, options) direkt auf, wenn Sie Abbruch oder wiederholsichere Ausführung benötigen.

• toOpenAITools(capabilities) gibt OpenAIFunctionTool[] zurück; runOpenAIToolCall(capabilities, call) gleicht nur den Anzeigenamen ab. Leere, fehlerhafte, null- oder primitive JSON-Argumentstrings werden zu {}; ein unbekannter Name wirft ein einfaches Error.
• toAnthropicTools / runAnthropicToolUse: Abgleich nur über den Anzeigenamen; unbekannte Namen werfen ein einfaches Error.
• toAISDKTools(capabilities, { jsonSchema? }) gibt ein nach Anzeigename schlüsseltes Objekt zurück; ein doppelter Anzeigename überschreibt den vorherigen Eintrag. Ohne den injizierten Wrapper ist parameters das rohe normalisierte JSON Schema. Jeder generierte execute(args) gibt CapabilityResult zurück.
• toGeminiTools / runGeminiFunctionCall: fehlende Argumente werden zu {}; unbekannte Namen werfen ein einfaches Error.
• toLangChainTools(capabilities, { tool }) und toOpenAIAgentsTools(capabilities, { tool }) erfordern die Fabrik des Aufrufers und sind generisch über deren Rückgabetyp. Ihre generierten Callbacks verbinden Ergebnis-Textteile mit einem Zeilenumbruch und bewahren weder isError noch die Typen der Content-Parts. Der Agents-Adapter übergibt das rohe normalisierte JSON Schema mit strict: false.
• toLlamaIndexTools(capabilities, { tool }) akzeptiert rohes JSON Schema, daher ist kein Zod erforderlich.
• toWorkersAITools(capabilities) gibt einfache Objekte mit gebundenen Ausführungsfunktionen zurück.
• toJSONSchemaTools(capabilities) erzeugt { name, description, parameters }; executeByName(capabilities, name, args) gleicht Anzeige- oder rohe Namen ab, mit Ersttreffer-Mehrdeutigkeit bei doppelten rohen Namen. Unbekannte Namen werfen ein einfaches Error.

Nächste Schritte

• Vergleichen Sie die framework adapters.
• Folgen Sie den Kontrollflussmustern unter error handling.
• Sehen Sie sich die recipes für fokussierte Integrationsmuster an.