ユーティリティ

@arcblock/did-connect-reactライブラリは、認証フロー、データ処理、API通信に関連する一般的なタスクを簡素化するために設計されたユーティリティ関数のコレクションをエクスポートします。コアコンポーネントとフックがほとんどのユースケースを処理しますが、これらのユーティリティは高度な統合やカスタム実装のための詳細な制御を提供します。

APIクライアント

createAxios

この関数は、事前設定されたaxiosインスタンスを作成するためのファクトリです。x-did-connect-versionやx-blocklet-visitor-idなどの必須ヘッダーを自動的に含み、Blockletベースのサービスとの適切な通信を保証します。アプリケーションでAPIクライアントを作成する推奨される方法です。

パラメータ

options object — 標準的なAxios設定オブジェクト。
lazyOptions object — 遅延送信のための設定。
- lazy boolean (default: false) — 遅延送信を有効にするかどうか。
- lazyTime number (default: 300) — 遅延送信のデバウンス時間（ミリ秒）。

戻り値

axiosInstance AxiosInstance — 設定済みのAxiosインスタンス。

例

apiClient.js

import { createAxios } from '@arcblock/did-connect-react/lib/utils';

const apiClient = createAxios({
  baseURL: '/api',
});

export default apiClient;

URLとポップアップの処理

これらの関数は、DID Connect認証プロセス中に使用されるURLとポップアップウィンドウの管理を支援します。

関数	説明
`encodeConnectUrl(url)`	URLを`__connect_url__`クエリパラメータとして安全に渡せるようにエンコードします。
`decodeConnectUrl(encoded)`	`encodeConnectUrl`でエンコードされたURLをデコードします。
`parseTokenFromConnectUrl(connectUrl)`	DID Connect URLからセッショントークン（`_t_`）を抽出します。
`openPopup(url, options)`	中央に配置された新しいポップアップウィンドウを開きます。`DidConnect`コンポーネントが内部で使用し、ウォレット接続インターフェースを表示します。ポップアップがブロックされた場合は`NotOpenError`をスローします。
`runPopup(config)`	`openPopup`で作成されたポップアップのライフサイクルを管理するプロミスベースのラッパーです。ポップアップからの`message`イベントをリッスンし、タイムアウトを処理し、認証フローが完了したときに解決します。
`decodeUrlParams()`	現在のウィンドウのURLからカスタムの`__did-connect__`パラメータを解析します。

例：カスタムポップアップフロー

customAuthButton.js

import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';

const handleCustomLogin = async () => {
  const authUrl = 'https://your-auth-service.com/connect';
  try {
    const popup = openPopup(authUrl);
    const result = await runPopup({ popup, timeoutInSeconds: 600 });
    console.log('Authentication successful:', result);
    // ログイン成功時の処理
  } catch (error) {
    console.error('Authentication failed:', error.message);
    // ポップアップが閉じられた、またはタイムアウトした場合の処理
  }
};

セッションとCookieの管理

これらのヘルパーは、ユーザーの接続情報をCookieに読み書きするために使用され、ページ読み込みをまたいだセッションの永続化を可能にします。

関数	説明
`getConnectedInfo(data)`	接続リクエストからの生のレスポンスデータを、Cookieストレージに適した標準化されたオブジェクトにフォーマットします。
`updateConnectedInfo(info, parsed)`	接続が成功した後、必要なCookie（`connected_did`、`connected_pk`、`connected_app`）を設定します。これにより、ライブラリは後続の認証チェックを最適化できます。
`getVisitorId()`	Cookieからユニークな訪問者IDを取得します。
`setVisitorId(id)`	Cookieにユニークな訪問者IDを設定します。

例

sessionManager.js

import { getConnectedInfo, updateConnectedInfo } from '@arcblock/did-connect-react/lib/utils';

// 'authResponse'がログインAPIから返されたオブジェクトであると仮定します
function persistSession(authResponse) {
  const connectedInfo = getConnectedInfo(authResponse);
  updateConnectedInfo(connectedInfo, true);
  console.log('セッション情報がCookieに保存されました。');
}

暗号化ユーティリティ

クライアントサイドでの暗号化または復号化が必要な高度なシナリオのために、ライブラリはtweetnacl-sealedbox-jsライブラリをラップするヘルパーを公開しています。

関数	説明
`encodeKey(key)`	キーを伝送用にBase64URLエンコードします。
`decodeKey(str)`	Base64URL文字列を`Uint8Array`キーにデコードします。
`encrypt(value, encryptKey)`	公開鍵を使用して文字列値を暗号化します。
`decrypt(value, encryptKey, decryptKey)`	対応する公開鍵と秘密鍵を使用してbase64文字列を復号化します。

エラーハンドリング

ユーザーにより良いフィードバックを提供するために、これらの関数を使用して技術的なエラーオブジェクトを人間が読めるメッセージに解析できます。

関数	説明
`getApiErrorMessage(err, defaultMessage)`	`axios`エラーオブジェクトからユーザーフレンドリーなエラーメッセージを抽出します。
`getWebAuthnErrorMessage(err, defaultMessage, t)`	WebAuthn/Passkey固有のエラー（例：ユーザーによるキャンセル、ブラウザ非対応）を処理し、ローカライズされたユーザーフレンドリーなメッセージを返します。

例

errorHandling.js

import { getApiErrorMessage } from '@arcblock/did-connect-react/lib/utils';
import apiClient from './apiClient';

async function fetchData() {
  try {
    const response = await apiClient.get('/data');
    return response.data;
  } catch (error) {
    const message = getApiErrorMessage(error, 'データの取得に失敗しました。');
    alert(message);
  }
}

これらのユーティリティを活用することで、より複雑でカスタマイズされた認証体験を構築できます。エクスポートされたすべてのメンバーとその型の完全なリストについては、APIリファレンスを参照してください。