extension-core-infrastructure

核心基礎架構

Caffeine AI 的核心基礎架構擴充套件。

概述

此元件提供所有專案的基礎建設：後端連線設定、Internet Identity 驗證鉤子（hooks）以及 actor 管理工具。

需求

"@caffeineai/core-infrastructure": "^1.1.0"
"@caffeineai/object-storage": "^1.1.0"
"@icp-sdk/auth": "^7.1.0"
"@icp-sdk/core": "^5.3.0"

@caffeineai/object-storage 是 core-infrastructure 的 peer 相依套件。每個專案都必須將其安裝為直接的 npm 相依套件（建置範本已包含這兩個套件）。

整合

核心基礎架構會自動包含在每個專案中，無需手動整合步驟。

前端

核心基礎架構的前端套件（@caffeineai/core-infrastructure）會自動包含在每個專案中。

應用程式進入點

使用 InternetIdentityProvider 和 QueryClientProvider 包裹應用程式：

import { InternetIdentityProvider } from "@caffeineai/core-infrastructure";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import ReactDOM from "react-dom/client";
import App from "./App";

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById("root")!).render(
  <QueryClientProvider client={queryClient}>
    <InternetIdentityProvider>
      <App />
    </InternetIdentityProvider>
  </QueryClientProvider>,
);

useInternetIdentity() — 驗證鉤子

提供 Internet Identity 的身份狀態、登入與登出功能。

回傳值

欄位	型別	說明
identity	Identity | undefined	使用者的身份（登入或還原 session 後可用）
login	() => void	開啟 II 彈出視窗。Fire-and-forget — 請勿使用 await。
clear	() => void	登出並清除儲存的身份。Fire-and-forget。
isAuthenticated	boolean	使用者擁有有效身份時為 true。請用此值控制 UI 顯示。
isInitializing	boolean	AuthClient 正在從 IndexedDB 載入時為 true
isLoggingIn	boolean	II 彈出視窗開啟中時為 true
isLoginSuccess	boolean	僅在互動式登入（非頁面重新載入還原）後為 true
isLoginError	boolean	登入或初始化失敗時為 true
loginError	Error | undefined	當 isLoginError 為 true 時的錯誤物件

驗證狀態生命週期

情境	loginStatus	isAuthenticated
頁面載入，無儲存的 session	"idle"	false
還原儲存的 session	"initializing"	false → true
重新載入後還原儲存的 session	"idle"	true
互動式登入進行中	"logging-in"	false
互動式登入剛完成	"success"	true
登入彈出視窗失敗/取消	"loginError"	false

重要： isLoginSuccess 僅在透過彈出視窗進行互動式登入後為 true — 頁面重新載入還原儲存身份時不會為 true。請一律使用 isAuthenticated 進行條件渲染。

使用方式

使用 isAuthenticated 控制需要驗證的 UI：

const { isAuthenticated } = useInternetIdentity();

{isAuthenticated ? <AuthenticatedApp /> : <LoginScreen />}

在初始化或登入中時停用登入按鈕：

const { login, isInitializing, isLoggingIn } = useInternetIdentity();

<button onClick={() => login()} disabled={isInitializing || isLoggingIn}>
  登入
</button>

login() 和 clear() 是 fire-and-forget — 鉤子的狀態欄位（isLoggingIn、isInitializing）會追蹤非同步生命週期。請勿將其包裹在區域的 useState / isPending 邏輯中。

useActor() — 後端 Actor 鉤子

建立並管理一個型別化的後端 actor 實例。當使用者身份變更（登入/登出）時，會自動重新建立 actor。

import { useActor } from "@caffeineai/core-infrastructure";
import { createActor } from "declarations/backend";

function MyComponent() {
  const { actor, isFetching } = useActor(createActor);

  // actor 在載入中為 null，之後為型別化的後端 actor
  if (!actor || isFetching) return <Loading />;

  // 直接呼叫後端方法
  const data = await actor.myBackendMethod();
}

回傳值

欄位	型別	說明
actor	T | null	型別化的後端 actor，載入中為 null
isFetching	boolean	actor 正在建立時為 true

當身份變更（登入、登出或 session 還原）時，actor 會自動以新身份重新建立，所有相依的查詢都會被標記為無效並重新擷取。