# @agg-build/auth 中文文档

规范地址：https://npmcn.com/package/%40agg-build/auth/

版本：4\.29\.0
npm 元数据更新时间：2026-10-22T19:33:52.413Z
中文译文更新时间：2026-11-08T03:30:11.268Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agg-build/auth
原文对照：https://npmcn.com/package/%40agg-build/auth/?lang=original
项目主页：https://docs.agg.market/
源码仓库：https://github.com/Snag-Solutions/Agg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：221 kB，55 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：bs58 ^6\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，wagmi ^3\.5\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@agg-build/ui ^4\.29\.0，@agg-build/hooks ^4\.29\.0，@solana/wallet-adapter-react ^0\.15\.39
- 首次发布：2026-04-27T19:41:56.401Z
- 最新版本发布：2026-10-22T19:33:52.070Z
- 近 30 天下载量：1908（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

AGG预测市场集成器的模块连接/签名UI和认证方法适配器(SIWE,SIWS,Google,Apple,Twitter/X,电子邮件魔法链接).

## 安装

```sh
npm install @agg-build/auth
```

也可以使用：`pnpm add @agg-build/auth`、`yarn add @agg-build/auth`、`bun add @agg-build/auth`

## README

# @agg-building/auth (英语)

模块连接 / 签名 UI 和 认证方法适配器 [恶作剧](https://docs.agg.market/) 预测市场聚合物。 掉进一个 `ConnectButton`选择 认证您想要启用的方法( SIWE, SIWS, Google, Apple, Twitter/ X, 电子邮件 magic-link) 和飞船 .

## 这是什么

`@agg-build/auth` 将特定供应商的认证集成从 [`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui)。作为单独适配器的每一种认证方法 —— 钱包提供者( SIWE, SIWS) 停留在子路径导入后, 因此它们的端口依赖性仅是 当你真正启用它们时就停了下来. `AggAuthProvider` 将流端对流端进行曲调: 打开选择器、 驱动钱包签名、 重定向到 OAuth 提供者、 电子邮件魔法 链接,处理后方向代码交换,透明地解决 Cloudflare Turnstile 当API需要时,挑战.

## 何时使用此软件包

-   您想要AGG的连接/ 登录 UX 不重建它 .
-   您想要只启用您的应用程序支持的认证方法 .
-   您想要重定向回调处理( OAuth + mail magic- link) 为您解析 .
-   你想要Cloudflare Turnstile 挑战处理系统.

如果您喜欢滚动自己的钱包, 请跳过此包并使用 `useAggAuth` 从 [`@agg-build/hooks`](https://www.npmjs.com/package/@agg-build/hooks) 直接说.

## 安装

核心软件包:

```bash
npm install @agg-build/sdk @agg-build/hooks @agg-build/ui @agg-build/auth liveline
```

只添加您需要的可选对等器 :

```bash
# SIWE / Ethereum
npm install wagmi viem

# SIWS / Solana
npm install @solana/wallet-adapter-react bs58
```

Google、苹果、Twitter/X和电子邮件的魔法链接流量不需要任何额外的同行 由 SDK 驱动的纯重定向流量 .

## 快开始

```tsx
import "@agg-build/ui/styles.css";
import { QueryClient, QueryClientProvider } from "@agg-build/hooks";
import { createAggClient } from "@agg-build/sdk";
import { AggProvider } from "@agg-build/ui";
import {
  AggAuthProvider,
  ConnectButton,
  createAppleAuthMethod,
  createEmailAuthMethod,
  createGoogleAuthMethod,
  createTwitterAuthMethod,
} from "@agg-build/auth";
import { useSiweAuthMethod } from "@agg-build/auth/siwe";
import { useSiwsAuthMethod } from "@agg-build/auth/siws";
import { WagmiProvider } from "wagmi";
import { wagmiConfig } from "./wagmi-config";

const client = createAggClient({
  appId: "your-app-id",
  baseUrl: "https://api.agg.market",
});
const queryClient = new QueryClient();

function AuthActions() {
  const siwe = useSiweAuthMethod({ statement: "Sign in to AGG" });
  const siws = useSiwsAuthMethod({ cluster: "mainnet", statement: "Sign in to AGG" });

  return (
    <AggAuthProvider
      methods={[
        siwe,
        siws,
        createGoogleAuthMethod(),
        createAppleAuthMethod(),
        createTwitterAuthMethod(),
        createEmailAuthMethod(),
      ]}
    >
      <ConnectButton />
    </AggAuthProvider>
  );
}

export default function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <AggProvider client={client}>
          <AuthActions />
        </AggProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}
```

`AggAuthProvider` 监视挂载上的当前 URL。 对于重定向方法,它读取 `code` 查询参数, 调用 `client.exchangeAuthCode(code)`,然后清理 URL。 没有额外 如果用户返回同一应用程序,则需要设置.

## 专用召回路线

如果您的应用路径重定向到一个单独的回调页面, 请将交换水分给自己 `useAggAuthCallback`数字 :

```tsx
import { useAggAuthCallback } from "@agg-build/auth";

export function AuthCallbackPage() {
  const { error, isHandled, isHandling, user } = useAggAuthCallback();

  if (isHandling) return <p>Finishing sign-in…</p>;
  if (error) return <p>{error.message}</p>;
  if (isHandled) return <p>Signed in as {user?.id}</p>;

  return <p>No AGG auth callback data was found.</p>;
}
```

呼回钩采用同一种食谱:

1.  分析 `code` 查询参数.
2.  打电话 `client.exchangeAuthCode(code)`。 。 。 .
3.  删除 `code` 从 URL 通过 `window.history.replaceState(...)`。 。 。 .

## 转折的挑战

AGG API 返回时 `challenge_required`, (中文(简体) ), `AggAuthProvider` 自动使 a Cloudflare Turnstile 部件, 提交已解决的符号, 并重试请求 。 部件是 如果用户的环境阻断了Turnstile, 则无法识别成功, 并优雅地降解。 你没有 需要直接渲染或配置部件.

## 可用的认证方法

| 导入路径 | 导出 | 端点 | 页:1 |
| --- | --- | --- | --- |
| `@agg-build/auth` | `createEmailAuthMethod()` | —— 说 | 魔法链接电子邮件流 |
| `@agg-build/auth` | `createGoogleAuthMethod()` | —— 说 | 基于重定向的 OAuth |
| `@agg-build/auth` | `createAppleAuthMethod()` | —— 说 | 基于重定向的 OAuth |
| `@agg-build/auth` | `createTwitterAuthMethod()` | —— 说 | 基于重定向的 OAuth |
| `@agg-build/auth/siwe` | `useSiweAuthMethod()` | `wagmi` | 钱包登录 |
| `@agg-build/auth/siws` | `useSiwsAuthMethod()` | `@solana/wallet-adapter-react`, (中文(简体) ), `bs58` | Solana 钱包签名; 兼容 |

通过您想要启用的方法 `AggAuthProvider` - 那个 `ConnectButton` 仅选择列表 包括方法.

### 自定义重定向 URL/ 导航

基于再定向的适配器接受一个 `redirectUrl` 和可选 `navigate` 函数 :

```tsx
createGoogleAuthMethod({
  redirectUrl: "https://yourapp.com/auth/callback",
  navigate: (url) => window.top?.location.assign(url),
});
```

### 自定义钱包拾取器( SIWE)

`useSiweAuthMethod` 接受可选选项 `connectorPicker` 来制作您的钱包选择模式 改为 `wagmi`默认值 :

```tsx
const siwe = useSiweAuthMethod({
  connectorPicker: async (connectors) => showMyWalletModal(connectors),
});
```

## `ConnectButton` 道具

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `buttonProps` | `ConnectButtonButtonProps` | 传入内心的道具 `Button` 组件 |
| `classNames` | `ConnectButtonClassNames` | 子元素的样式覆盖 |
| `disabled` | `boolean` | 禁用按钮 |
| `onAuthMethodSelect` | `(methodId: AuthMethodId) => void | Promise<void>` | 用户选择认证方法时调用 |
| `onDepositClick` | `() => void | Promise<void>` | 用户点击存款时调用 |
| `onDisconnect` | `() => void | Promise<void>` | 已断开 |
| `onProfileClick` | `() => void | Promise<void>` | 用户点击配置文件时调用 |
| `onWithdrawClick` | `() => void | Promise<void>` | 用户点击退出时调用 |

认证时,按钮会随动作按钮倒入用户的配置文件芯片 (保存,退出,配置,断开). 用回调道具把它们接到你的应用程序上 导航或模式系统.

## 主要出口

| 导入路径 | 导出 | 说明 |
| --- | --- | --- |
| `@agg-build/auth` | `AggAuthProvider` | 管弦乐选择器、调回调用和旋转 |
| `@agg-build/auth` | `ConnectButton` | 滴入连接/ 账户芯片 |
| `@agg-build/auth` | `useAggAuthFlow` | 访问选择者/ 流程状态( 由自定义 UI 使用) |
| `@agg-build/auth` | `useAggAuthCallback` | 手动水合重定向回调页面 |
| `@agg-build/auth` | `createEmailAuthMethod` | 魔法链接电子邮件适配器 |
| `@agg-build/auth` | `createGoogleAuthMethod` | 谷歌 OAuth 适配器 |
| `@agg-build/auth` | `createAppleAuthMethod` | 苹果 OAuth 适配器 |
| `@agg-build/auth` | `createTwitterAuthMethod` | Twitter/X OAuth 适配器 |
| `@agg-build/auth/siwe` | `useSiweAuthMethod` | SIWE 适配器( 需要) `wagmi`(中文(简体) ) |
| `@agg-build/auth/siws` | `useSiwsAuthMethod` | SIWS 适配器( 需要) `@solana/wallet-adapter-react` + 键 `bs58`(中文(简体) ) |

## 建筑

-   `@agg-build/sdk` 拥有 auth API 调用和会话键存储 .
-   `@agg-build/hooks` 内部拥有共享认证/会话状态 `AggProvider`。 。 。 .
-   `@agg-build/ui` 舰只使用通用UI原始.
-   `@agg-build/auth` 船舶认证方法适配器+连接/签名 UX.

## 入境点

| 条目 | 目的 |
| --- | --- |
| `@agg-build/auth` | `AggAuthProvider`, (中文(简体) ), `ConnectButton`, OAuth + 电子邮件适配器 |
| `@agg-build/auth/connect-button` | `ConnectButton` 仅包含组件(小于导入) |
| `@agg-build/auth/oauth` | `createAppleAuthMethod`, (中文(简体) ), `createGoogleAuthMethod`, (中文(简体) ), `createTwitterAuthMethod` |
| `@agg-build/auth/email` | `createEmailAuthMethod` |
| `@agg-build/auth/siwe` | `useSiweAuthMethod` (所需经费) `wagmi`(中文(简体) ) |
| `@agg-build/auth/siws` | `useSiwsAuthMethod` (需要索拉纳钱包适配器) |

## 同伴依赖关系

要求 :

-   `@agg-build/hooks`
-   `@agg-build/ui`
-   `react` ^18.0.0或^19.0
-   `react-dom` ^18.0.0或^19.0

可选(与特定适配器挂钩):

-   `wagmi` ^ 3. 5.0 — 锡瓦
-   `@solana/wallet-adapter-react` ^0.15.39 - SIWS (英语)
-   `bs58` ^ 6. 0.0 — SIWS 签名编码

## 链接

-   文 件 - 存档副本 [https://docs.agg.market/ 互联网档案馆的存檔,存档日期2013-12-02](https://docs.agg.market/)
-   童话书—— [https://storybook.agg.market/ 页面存档备份,存于互联网档案馆](https://storybook.agg.market/)
-   Demo app - 软件 [https://demo.agg.market/ 页面存档备份,存于互联网档案馆](https://demo.agg.market/)
-   香草SDK - - 。 [`@agg-build/sdk`](https://www.npmjs.com/package/@agg-build/sdk)
-   反应钩- [`@agg-build/hooks`](https://www.npmjs.com/package/@agg-build/hooks)
-   贸易UI - [`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui)

## 许可证

麻省理工学院

## 常见问题

### @agg-build/auth 是什么？

AGG预测市场集成器的模块连接/签名UI和认证方法适配器\(SIWE,SIWS,Google,Apple,Twitter/X,电子邮件魔法链接\)\.

### 如何安装 @agg-build/auth？

在项目目录运行 npm install @agg-build/auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@agg-build/ui（^4\.29\.0）、@agg-build/hooks（^4\.29\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @agg-build/auth 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agg-build/auth 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @agg-build/auth 可以商用吗？

@agg-build/auth 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agg-build/auth 的下载量有多少？

根据 npm 官方下载统计，@agg-build/auth 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,908 次，日均约 64 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agg-build/auth 还在维护吗？

最新版本 4\.29\.0 发布于 2026/10/23（16 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。