コネクタと認証情報

コネクターはカタログ内の統合を表します。接続とは、そのコネクターを 1 人のアプリケーションユーザー向けに構成したものです。このページでは、資格情報のフィールド名を想定せずに、サーバー側のセットアップフローを構築します。

SDK には、ホスト型の資格情報フォームや OAuth UI の API はありません。アプリケーションがセットアップ画面を描画して認可し、そのバックエンドからコネクターのメソッドを呼び出します。

コネクターの遅延評価ハンドルを作成する

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

どちらの行もリクエストを送信しません。ハンドルは後の操作に備えてユーザースコープとスラッグを保持します。コネクターのスラッグは API にそのまま渡されます。externalId と異なり、コンストラクターはスラッグ専用のバリデーターを適用しません。

必要な資格情報フィールドを読み取る

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

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

schema() はカタログの詳細を読み取り、接続が存在する前でも機能します。フィールドには type、label、required、group、docs_url、placeholder、allowed の値が含まれることがあります。これらの記述子を使って、独自のフォームを構築または検証してください。

接続を作成して値を保存する

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() はリクエストを実行します。Vinkius API の契約では、これはユーザーとコネクターに対する get-or-create であるため、SDK はこの操作を一時的な障害の再試行に対してべき等として扱います。繰り返し呼び出しても、ネットワーク I/O は発生します。

ハンドルは返された接続 ID を記憶します。同じハンドルに対する後続の credentials.set()、credentials.status()、コネクタースコープの capabilities() の呼び出しは、再び検索しなくてもそれを使用できます。

コネクターのステータスを解釈する

const status = await github.status();

status() は接続を一覧表示し、存在しない場合は例外をスローする代わりに not_connected を返します。credentials.status()、credentials.set()、disconnect()、コネクタースコープの capabilities() は接続を必要とし、ConnectorNotConnectedError をスローすることがあります。

資格情報の値は書き込み専用

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

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

API が返すのはスキーマと設定済みキーのフラグであって、保存された値ではありません。ステータスを資格情報の取得やコピーの手段として使わないでください。送信された値は、サービスによってコネクターのスキーマに対して検証されます。

既存の接続をすべて一覧表示する

const summaries = await user.connectors();

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

この一覧には既存の接続のみが含まれ、各接続レスポンスから同じ 4 つのステータス値が導出されます。

アクションを読み込むか、接続を切断する

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

await github.disconnect();

disconnect() は接続 ID を解決し、接続を削除し、成功後にそのハンドルの記憶を消去します。別のハンドルには別の記憶があります。ハンドルの外部で接続が変更された場合、以前に記憶された ID が古くなる可能性があります。

カタログからコネクターを見つける

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) は同じカタログエンドポイントに q を送信します。フィルタリングはサービス側の対応状況に依存します。q を無視するサービスは、フィルター前の一覧を返すことがあります。

次のステップ

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