extension-core-infrastructure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Core Infrastructure

核心基础设施

Core infrastructure extension for Caffeine AI.

为Caffeine AI提供的核心基础设施扩展。

Overview

概述

This component provides the foundational infrastructure for all projects: backend connection configuration, Internet Identity authentication hooks, and actor management utilities.

该组件为所有项目提供基础架构支持：后端连接配置、Internet Identity认证钩子以及角色管理工具。

Requirements

依赖要求

Requries

"@icp-sdk/auth": "^7.1.0"
"@icp-sdk/core": "^5.3.0"

需要

"@icp-sdk/auth": "^7.1.0"
"@icp-sdk/core": "^5.3.0"

Integration

集成方式

Core infrastructure is automatically included in every project. No manual integration steps are required.

核心基础设施会自动包含在每个项目中，无需手动执行集成步骤。

Frontend

前端部分

The core-infrastructure frontend package (

@caffeineai/core-infrastructure

) is automatically included in every project.

核心基础设施前端包（

@caffeineai/core-infrastructure

）会自动包含在每个项目中。

App Entry Point

应用入口

Wrap the app with

InternetIdentityProvider

and

QueryClientProvider

typescript

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

使用

InternetIdentityProvider

和

QueryClientProvider

包裹应用：

typescript

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()

— Authentication Hook

useInternetIdentity()

— 认证钩子

Provides identity state, login, and logout for Internet Identity.

提供Internet Identity的身份状态、登录和登出功能。

Return Values

返回值

Field	Type	Description
`identity`	`Identity \| undefined`	The user's identity (available after login or session restore)
`login`	`() => void`	Opens the II popup. Fire-and-forget — do not `await` .
`clear`	`() => void`	Logs out and clears stored identity. Fire-and-forget.
`isAuthenticated`	`boolean`	`true` when user has a valid identity. Use this for UI gating.
`isInitializing`	`boolean`	`true` while `AuthClient` is loading from IndexedDB
`isLoggingIn`	`boolean`	`true` while the II popup is open
`isLoginSuccess`	`boolean`	`true` only after interactive login (NOT after page reload restore)
`isLoginError`	`boolean`	`true` if login or initialization failed
`loginError`	`Error \| undefined`	The error object when `isLoginError` is `true`

字段	类型	描述
`identity`	`Identity \| undefined`	用户身份（登录或会话恢复后可用）
`login`	`() => void`	打开II弹窗。无需等待，直接调用即可。
`clear`	`() => void`	登出并清除存储的身份信息。无需等待，直接调用即可。
`isAuthenticated`	`boolean`	用户拥有有效身份时为 `true` 。用于UI权限控制。
`isInitializing`	`boolean`	`AuthClient` 从IndexedDB加载时为 `true`
`isLoggingIn`	`boolean`	II弹窗打开时为 `true`
`isLoginSuccess`	`boolean`	仅在交互式登录完成后为 `true` （页面重载恢复会话时不会为 `true` ）
`isLoginError`	`boolean`	登录或初始化失败时为 `true`
`loginError`	`Error \| undefined`	`isLoginError` 为 `true` 时的错误对象

Auth State Lifecycle

认证状态生命周期

Scenario	`loginStatus`	`isAuthenticated`
Page load, no stored session	`"idle"`	`false`
Restoring stored session	`"initializing"`	`false` → `true`
Stored session restored after reload	`"idle"`	`true`
Interactive login in progress	`"logging-in"`	`false`
Interactive login just completed	`"success"`	`true`
Login popup failed / cancelled	`"loginError"`	`false`

IMPORTANT:

isLoginSuccess

is only

true

after an interactive login via the popup — NOT when a stored identity is restored on page reload. Always use

isAuthenticated

for conditional rendering.

场景	`loginStatus`	`isAuthenticated`
页面加载，无存储会话	`"idle"`	`false`
恢复存储会话中	`"initializing"`	`false` → `true`
页面重载后恢复存储会话	`"idle"`	`true`
交互式登录进行中	`"logging-in"`	`false`
交互式登录刚完成	`"success"`	`true`
登录弹窗失败/取消	`"loginError"`	`false`

重要提示：

isLoginSuccess

仅在通过弹窗完成交互式登录后为

true

——页面重载恢复存储身份时不会为

true

。条件渲染请始终使用

isAuthenticated

。

Usage

使用示例

Gate authenticated UI on

isAuthenticated

typescript

const { isAuthenticated } = useInternetIdentity();

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

Disable the login button while initializing or logging in:

typescript

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

<button onClick={() => login()} disabled={isInitializing || isLoggingIn}>
  Sign in
</button>

login()

and

clear()

are fire-and-forget — the hook's state fields (

isLoggingIn

isInitializing

) track the async lifecycle. Do not wrap them in local

useState

isPending

logic.

基于

isAuthenticated

控制认证后UI的显示：

typescript

const { isAuthenticated } = useInternetIdentity();

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

在初始化或登录过程中禁用登录按钮：

typescript

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

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

login()

和

clear()

无需等待结果——钩子的状态字段（

isLoggingIn

、

isInitializing

）会跟踪异步生命周期。无需在本地使用

useState

isPending

逻辑。

useActor()

— Backend Actor Hook

useActor()

— 后端角色钩子

Creates and manages a typed backend actor instance. Automatically re-creates the actor when the user's identity changes (login/logout).

typescript

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

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

  // actor is null while loading, then the typed backend actor
  if (!actor || isFetching) return <Loading />;

  // Call backend methods directly
  const data = await actor.myBackendMethod();
}

创建并管理类型化的后端角色实例。当用户身份变更（登录/登出）时，会自动重新创建角色实例。

typescript

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

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

  // 加载时actor为null，之后变为类型化的后端角色
  if (!actor || isFetching) return <Loading />;

  // 直接调用后端方法
  const data = await actor.myBackendMethod();
}

Return Values

返回值

Field	Type	Description
`actor`	`T \| null`	The typed backend actor, or `null` while loading
`isFetching`	`boolean`	`true` while the actor is being created

When the identity changes (login, logout, or session restore), the actor is automatically re-created with the new identity and all dependent queries are invalidated and refetched.

字段	类型	描述
`actor`	`T \| null`	类型化的后端角色，加载时为 `null`
`isFetching`	`boolean`	创建角色实例时为 `true`

当身份变更（登录、登出或会话恢复）时，会使用新身份自动重新创建角色实例，所有相关查询都会失效并重新获取数据。

extension-core-infrastructure

Original

Translation

Core Infrastructure

核心基础设施

Overview

概述

Requirements

依赖要求

Integration

集成方式

Frontend

前端部分

App Entry Point

应用入口

`useInternetIdentity()`
— Authentication Hook

`useInternetIdentity()`
— 认证钩子

Return Values

返回值

Auth State Lifecycle

认证状态生命周期

Usage

使用示例

`useActor()`
— Backend Actor Hook

`useActor()`
— 后端角色钩子

Return Values

返回值