クイックスタート

このクイックスタートでは、アプリケーションのユーザー 1 名に対して GitHub アカウントを接続し、コネクターの認証情報を保存し、そのユーザーが利用できるアクションを検出したうえで、1 つのアクションを実行します。同じ流れは他のコネクターでも機能します。認証情報のフィールドと Capability は API から提供されます。

前提条件

• Node.js 18 以降、または fetch を備えたサーバー実行環境
• @vinkius/connect がインストール済みであること（Installation を参照）
• サーバーの環境変数に Vinkius の App ID と Application Key が設定されていること
• サンプルコネクター用の GitHub トークン

完全なクイックスタート

1. 再利用可能なクライアントを作成する

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

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

構築時には、認証情報のプレフィックス、ベース URL、fetch の利用可能性が検証されます。HTTP リクエストは送信されません。

2. ユーザーとコネクターのハンドルを作成する

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

どちらの呼び出しも遅延実行です。信頼されたアプリケーションユーザー ID とコネクターの slug を保持しますが、リクエストは送信しません。user.ensure({ plan: 'pro' }) は省略可能で、API にユーザーを明示的に upsert させたい場合や、秘密でないメタデータを保存したい場合にのみ必要です。

3. 接続を作成または取得する

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

これにより 1 件の POST リクエストが送信されます。Vinkius API はこのリクエストを、このアプリケーションユーザーとコネクターに対する get-or-create として扱います。connect() を再度呼び出してもリクエストは送信されますが、重複を作成する代わりに同じ論理的な接続が返されます。

4. コネクターの認証情報を保存する

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

console.log(credentialState.configured);

これにより、既存の接続に対して 1 件の PUT リクエストが送信されます。レスポンスはどのキーが構成済みかを報告するものであり、保存された値は返しません。フィールドが不明なコネクターの場合は、接続する前に await github.credentials.schema() を呼び出してください。スキーマの参照はカタログを読み取るだけであり、接続は必要ありません。

5. このユーザーの Capability を読み込む

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

これにより 1 件の GET リクエストが送信されます。include はサーバーに送信されるため、レスポンスは GitHub に限定されます。空のセットも有効です。たとえば、コネクターの準備ができていない場合や、一致するアクションを 1 つも公開していない場合が挙げられます。

6. アクションを実行する

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

実行により 1 件の POST リクエストが送信されます。空でなく安定した idempotency キーにより、SDK は一時的な失敗を、同じ論理アクションを新しい操作として扱うことなく再試行できます。SDK はキーが空でないことを検証しません。アプリケーション側でキーを生成し、検証してください。

リクエストのまとめ

isError: true で解決された実行は、コネクターレベルの結果です。認証、HTTP、タイムアウト、トランスポートの失敗は、通常は代わりに VinkiusError のサブクラスをスローします。詳細は Error handling を参照してください。

次のステップ

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