AI Connect/Get started/インストール
インストール
@vinkius/connect をサーバーランタイムに追加し、アプリケーションのクレデンシャルを設定して、API 接続を確認します。
パッケージをバックエンドにインストールし、再利用可能な Vinkius インスタンスを1つ作成します。クライアントはユーザーごとの状態ではなくアプリケーションレベルの設定を保存するため、同じインスタンスで多くのユーザーのリクエストに対応できます。
前提条件
- Node.js 18 以降、または
fetchを提供するその他のサーバーランタイム（Node 18+、Bun、Deno、エッジランタイム） vk_app_で始まる Vinkius の App IDvk_app_sk_で始まる Vinkius の Application Key
API クレデンシャルの取得
Vinkius Connect は、Vinkius Cloud の Application にある2つの値で認証します。
| 値 | プレフィックス | 説明 |
|---|---|---|
appId | vk_app_... | Application の公開 ID。テナントを識別します |
apiKey | vk_app_sk_... | Application Key。バックエンドがユーザーの代理として行動するために使うシークレットです |
Vinkius Cloud のダッシュボードで作成するには：
- Build AI Apps（
/ai-agents）を開き、New AI Application をクリックします。名前（例：Acme Copilot）を付けて作成します。 - アプリケーションを開きます。App ID（
vk_app_...）はアプリ名の下とページ URL に表示されます。appIdにコピーしてください。 - App Keys タブに移動し、New Key をクリックします。バックエンドに必要な権限を選択し、Create Key をクリックします。
- Application Key（
vk_app_sk_...）は、"Copy this key now" ダイアログに一度だけ表示されます。apiKeyにコピーしてください。後から取得することはできません。
同じ App Keys タブから、いつでもキーをローテーションまたは失効できます。ローテーションすると古いキーは直ちに無効になり、新しいキーは一度だけ表示されます。
vk_app_sk_... はサーバー側のみで保持してください。環境変数またはシークレットマネージャーに保存します。ブラウザー、モバイルアプリ、ユーザーが管理するあらゆるクライアントに送信しないでください。
パッケージのインストール
npm install @vinkius/connect同等のコマンドは pnpm add @vinkius/connect、yarn add @vinkius/connect、bun add @vinkius/connect です。パッケージは TypeScript の型をバンドルしたデュアル ESM + CommonJS として提供され、実行時依存はありません。
サーバーの環境変数を設定
VINKIUS_APP_ID=vk_app_xxxxxxxxxxxxxxxx
VINKIUS_APP_KEY=vk_app_sk_xxxxxxxxxxxxxxxxxxxxxxxxサーバー専用モジュールを作成
// lib/vinkius.ts — import this module only from server code
import { Vinkius } from '@vinkius/connect';
function required(name: 'VINKIUS_APP_ID' | 'VINKIUS_APP_KEY'): string {
const value = process.env[name];
if (!value) throw new Error(`Missing ${name}`);
return value;
}
export const vinkius = new Vinkius({
appId: required('VINKIUS_APP_ID'),
apiKey: required('VINKIUS_APP_KEY'),
});コンストラクターは App ID とキーのプレフィックスを検証し、指定があれば baseUrl を解析し、fetch 実装を要求します。リクエストは送信しません。オプションの数値やコールバックすべてに対して実行時の範囲検証は行わないため、timeoutMs、maxRetries、hooks、カスタム命名関数はアプリケーション側で管理してください。
ランタイムにグローバルな fetch がない場合は、互換性のある実装を渡してください。
const vinkius = new Vinkius({
appId,
apiKey,
fetch: customFetch,
});クライアントオプション
new Vinkius({
appId: 'vk_app_...',
apiKey: 'vk_app_sk_...',
baseUrl: 'https://api.vinkius.com', // default
timeoutMs: 30_000, // default
maxRetries: 2, // default (idempotent requests only)
fetch: globalThis.fetch, // override for tests/edge
userAgent: 'acme-ai/1.0', // appended to the default User-Agent
namespaceCapability: (connector, name) => `${connector}__${name}`, // default
hooks: {
onRequest: ({ method, url }) => {}, // headers/body are redacted
onResponse: ({ status, requestId }) => {},
},
});リクエストでクレデンシャルを検証
ハンドルだけを作成する確認では API に接続しません。実際のスモークテストにはカタログの読み取りを使用してください。
import { VinkiusError } from '@vinkius/connect';
import { vinkius } from './lib/vinkius';
async function checkVinkiusConnection(): Promise<void> {
try {
const page = await vinkius.catalog.list({ page: 1 });
console.log(`Vinkius API reachable; received ${page.data.length} connectors`);
} catch (error: unknown) {
if (error instanceof VinkiusError) {
console.error({
code: error.code,
status: error.status,
requestId: error.requestId,
});
}
throw error;
}
}
await checkVinkiusConnection();この確認により、ランタイムが API に到達できること、およびアプリケーションのクレデンシャルが受け入れられることが検証されます。ローカルの ConfigError はリクエスト前に発生し、AuthError は HTTP 401 または 403 のレスポンスを表します。
ユーザーハンドルを作成
const user = vinkius.user('alice_123');user() はリクエストを送信しません。ID はアプリケーションの安定したユーザー識別子である必要があります。1〜255文字、vk_app_user_ で始まらず、空白、スラッシュ、バックスラッシュを含まないこと。
user.ensure(metadata) は任意です。明示的な API アップサートが必要な場合や、シークレットでないメタデータを添付したい場合に呼び出してください。ハンドルを取得するためだけに呼び出すものではありません。