# @cointracker/tax-kit 中文文档

规范地址：https://npmcn.com/package/%40cointracker/tax-kit/

版本：2\.5\.0
npm 元数据更新时间：2026-11-05T18:29:28.625Z
中文译文更新时间：2026-11-10T10:51:02.460Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40cointracker/tax-kit
原文对照：https://npmcn.com/package/%40cointracker/tax-kit/?lang=original
项目主页：https://github.com/coin-tracker/client-apps#readme
源码仓库：https://github.com/coin-tracker/client-apps

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

- 包体积（解压后）：69.3 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^16\.8 \|\| ^17\.0 \|\| ^18\.0 \|\| ^19\.0 \|\| ^19\.0\.0-rc，react-dom ^16\.8 \|\| ^17\.0 \|\| ^18\.0 \|\| ^19\.0 \|\| ^19\.0\.0-rc，@types/react \*，@types/react-dom \*
- 首次发布：2025-11-04T18:29:53.037Z
- 最新版本发布：2026-11-05T18:29:28.446Z
- 近 30 天下载量：3916（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 34 个）

## 中文简介

提供成本基础数据的硬跟踪器SDK

## 安装

```sh
npm install @cointracker/tax-kit
```

也可以使用：`pnpm add @cointracker/tax-kit`、`yarn add @cointracker/tax-kit`、`bun add @cointracker/tax-kit`

## README

# @ cointracker/ tax- kit

用于提供成本基础数据和将税收计算功能纳入您的应用程序的CoinTracker SDK.

## 安装

```bash
npm install @cointracker/tax-kit
```

## 使用量

```tsx
import { TaxKitProvider, useTaxKit } from '@cointracker/tax-kit';

// Wrap your app with the TaxKitProvider
function App() {
  const fetchAccessToken = async () => {
    // Fetch access token from your backend
    const response = await fetch('/api/user-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
    });
    const data = await response.json();
    return data.access_token;
  };

  return (
    <TaxKitProvider fetchAccessToken={fetchAccessToken}>
      <YourApp />
    </TaxKitProvider>
  );
}

// Use the useTaxKit hook in your components
function YourComponent() {
  const {
    open,
    isSyncingTransactions,
    lastSyncUpdatedTimestamp,
    error,
    numberOfConnections,
    syncingConnections,
    isCalculatingCostBasis,
    disconnectUser,
    isUserConnected,
  } = useTaxKit();

  return (
    <div>
      <button onClick={open}>Connect CoinTracker</button>
      {isSyncingTransactions && <p>Syncing transactions...</p>}
      {syncingConnections && <p>Syncing connections...</p>}
      {isCalculatingCostBasis && <p>Calculating cost basis...</p>}
      {isUserConnected && (
        <div>
          <p>Connected with {numberOfConnections} connection(s)</p>
          <button onClick={disconnectUser}>Disconnect</button>
        </div>
      )}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}
```

## Hook API 参考文献

这个 `useTaxKit` 钩子返回以下属性:

-   **`open`** - 打开CoinTracker模式,供用户连接账户的功能
-   **`isTaxKitOpen`** - 布尔表示当前税基特模式是否打开
-   **`isTaxKitLoading`** - 布尔表示税套是否正在装入(计算状态)
-   **`isSyncingTransactions`** - 布尔表示SDK是否正在同步交易给合伙人
-   **`lastSyncUpdatedTimestamp`** - 上次同步更新的时标( 自 epoc 时代起), 如果从未同步则无效
-   **`error`** - 在同步或认证过程中遇到的任何错误(TaxKitError QQ 无效)
-   **`numberOfConnections`** - 用户配置的连接数( QQ为空)
-   **`syncingConnections`** - 布尔表示SDK是否正在同步连接
-   **`isCalculatingCostBasis`** - 布尔表示SDK是否正在计算成本基础
-   **`taxKitStatus`** - 当前 TaxKit 同步状态与标题、描述和动作标签( TaxKitstatusInfo QQ 无效)
-   **`disconnectUser`** - 将用户断开并重置税包到空状态的函数 。 返回承诺
-   **`isUserConnected`** - 布尔表示用户是否已启动税套流

### 税基状态值

这个 `taxKitStatus` 对象包含一个 `status` 字段,其中有一个值:

-   **`GET_STARTED`** - 用户需要连接账户并启动自动同步
-   **`SYNCED`** - 成本基础已成功发送给合作伙伴
-   **`TRANSACTIONS_NEED_REVIEW`** - 交易在进行前需要用户审查
-   **`UNABLE_TO_SYNC_TO_PARTNER`** - 由于错误, 无法同步到伴侣
-   **`UPGRADE_PLAN_NEEDED`** - 用户已达到计划极限,需要升级
-   **`READY_TO_IMPORT`** - 税地可以进口了 等待用户确认 .
-   **`COST_BASIS_FAILED`** - 成本基础计算失败
-   **`FIX_API_CONNECTIONS`** - API 连接需要固定
-   **`IMPORTING_COST_BASIS`** - 向合伙人发税地
-   **`SYNCING_WALLETS_AND_CALCULATING_COST_BASIS`** - 同步钱包和计算成本
-   **`ERROR`** - 税务包出错(例如认证错误或通用错误)

## 配置

`TaxKitProvider` 组合配置为三个可选子对象: `theme`, (中文(简体) ), `options`,以及 `metadata`复召(`onOpenLink`, (中文(简体) ), `onDisconnectUser`, (中文(简体) ), `onPartnerImportTransactionsSuccess`, (中文(简体) ), `onReceivedAdditionalMetadata`和 `copy` 留在顶层.

### 主题

通过颜色符号和暗模式偏好 `theme`数字 :

```tsx
<TaxKitProvider
  fetchAccessToken={fetchAccessToken}
  theme={{
    mode: 'dark', // optional — defaults to the user's OS preference
    light: {
      radius: '0.5rem',
      spacing: '0.25rem',
      fontSans: '"Inter", sans-serif',
      background: 'rgb(255, 255, 255)',
      foreground: 'rgb(10, 11, 13)',
      primary: 'rgb(0, 82, 255)',
      // ...see ThemeContract for all available tokens
    },
    dark: {
      radius: '0.5rem',
      spacing: '0.25rem',
      fontSans: '"Inter", sans-serif',
      background: 'rgb(10, 11, 13)',
      foreground: 'rgb(245, 248, 255)',
      primary: 'rgb(55, 115, 245)',
    },
  }}
>
  <YourApp />
</TaxKitProvider>
```

> **提示 :** 记住 `theme` 联合国 `light`编号 :`dark` 子对象)与 `useMemo` 如果您的父组件频繁重交—— 这可以避免冗余 `CONFIG` 给iframe的留言.

#### 伙伴品牌(日志和字体)

`theme` 接受iframe内想要自己标识和品牌字体的合作伙伴的三个可选字段.

##### `theme.partnerLogo`

将你的标志在 Iframe 头来代替 SDK 的内置标记。 接受单个字符串 URL( 两种模式都使用) 或每个模式对象 :

```tsx
theme={{
  // Single URL — same logo in light and dark mode
  partnerLogo: 'https://cdn.your-partner.com/logo.svg',
}}
```

```tsx
theme={{
  // Separate logos so a dark logo can be used on light backgrounds, and vice versa
  partnerLogo: {
    light: 'https://cdn.your-partner.com/logo-dark-on-light.svg',
    dark: 'https://cdn.your-partner.com/logo-light-on-dark.svg',
  },
}}
```

注释:

-   图像由您托管, 位于您 CDN 或 来源上的 CORS 可访问 URL 。 偏好SVG;如果将PNG船载出,请保持小(≤128px平方). 视觉尺寸被锁定在iframe头上——没有超大小的图像打破布局的风险——但带宽仍在你身上.
-   备选文本是自动从伙伴弹出(例如:. `"Coinbase logo"`)),不需要通过.
-   何时 `partnerLogo` 尚未设置, SDK 使用它内置的标识来表示已知的伴侣 sults(`coinbase`, (中文(简体) ), `kraken`) (中文(简体) ).

##### `theme.fonts`

自办 `@font-face` 定义 `woff2`编号 :`woff`编号 :`ttf`编号 :`otf` 您从自己的CDN服务的文件。 每个条目都是逐字注入的,所以您可以控制格式,重量,样式,以及 `font-display`。 。 。 .

```tsx
theme={{
  fonts: [
    {
      family: 'Partner Sans',
      src: 'https://cdn.your-partner.com/partner-sans-regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      family: 'Partner Sans',
      src: 'https://cdn.your-partner.com/partner-sans-bold.woff2',
      weight: '700',
      style: 'normal',
    },
  ],
  light: { fontSans: '"Partner Sans", sans-serif', /* ...other tokens */ },
  dark: { fontSans: '"Partner Sans", sans-serif', /* ...other tokens */ },
}}
```

##### `theme.fontStylesheets`

外部字体样式表 URL — Google 字体, Adobe 字体, Bunny 字体等. iframe 注射每个作为 `<link rel="stylesheet">`,所以提供者处理 `@font-face` 规则, unicode-range 子设置和格式谈判.

```tsx
theme={{
  // Single URL
  fontStylesheets:
    'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
}}
```

```tsx
theme={{
  // Multiple URLs
  fontStylesheets: [
    'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
    'https://use.typekit.net/your-kit-id.css',
  ],
  light: { fontSans: '"Inter", sans-serif', /* ... */ },
}}
```

使用 `fonts` 用于控制源 URL 的自托管品牌字体, `fontStylesheets` 用于现成的网络字体。 两者是独立的——要么使用,要么使用,要么不使用.

### 选项

行为开关( 环境、 流量、 上覆样式、 UI 切换) `options`数字 :

```tsx
<TaxKitProvider
  fetchAccessToken={fetchAccessToken}
  options={{
    mode: 'production', // 'production' | 'alpha' | 'mock'
    flow: 'one-way', // 'one-way' | 'continuous'
    overlayMode: 'responsive', // 'drawer' | 'dialog' | 'responsive'
    defaultOpen: false,
    helpLinkUrl: 'https://help.<your-partner>.com/tax',
  }}
>
  <YourApp />
</TaxKitProvider>
```

## 嵌入您自己的对话框

默认iframe是一个固定的,全视图的覆盖. 内置套件 **你们自己** 对话框/绘图,通过一个 `container` iframe 制成的DOM节点(或参考). iframe被传送到那个节点并填满它,而提供者可以在你的树上保持高架(所以) `useTaxKit()` 继续全应用程序工作 :

```tsx
function App() {
  // Keep this node mounted (toggle the dialog's visibility rather than
  // unmounting it) so the iframe preserves its state across open/close.
  const dialogBodyRef = useRef<HTMLDivElement>(null);

  return (
    <TaxKitProvider
      fetchAccessToken={fetchAccessToken}
      options={{ overlayMode: 'dialog' }}
      container={dialogBodyRef}
    >
      <YourApp />
      <YourDialog>
        <div ref={dialogBodyRef} style={{ width: '100%', height: '100%' }} />
      </YourDialog>
    </TaxKitProvider>
  );
}
```

奥米 `container` 用于默认的全屏幕覆盖。 打开并关闭工具箱 `useTaxKit().open()` 编号 : `close()`,并驱动对话框的能见度从 `isTaxKitOpen`。 。 。 .

## 自定义元数据

SDK支持在母应用程序和SDK iframe之间通过自定义元数据. 这对于需要快速执行的针对特定伙伴的数据有用,而不需要用新的专用道具更新税基SDK.

### 传递元数据到 SDK

```tsx
<TaxKitProvider
  fetchAccessToken={fetchAccessToken}
  metadata={{
    customField: 'any-value',
  }}
>
  <YourApp />
</TaxKitProvider>
```

### 保留密钥

里面有一个钥匙 `metadata` 有SDK的特殊处理:

-   **`promoCode`** (单位:千美元)`string`)——作为用户的促销码被应用.

所有其他密钥均由合伙人定义并透明地传递到iframe.

```tsx
<TaxKitProvider
  fetchAccessToken={fetchAccessToken}
  metadata={{
    promoCode: 'PARTNER_2026',
    // arbitrary partner extras are allowed alongside reserved keys
    customField: 'any-value',
  }}
>
  <YourApp />
</TaxKitProvider>
```

### 从 SDK 接收元数据

SDK 可以使用 `onReceivedAdditionalMetadata` 回调 :

```tsx
<TaxKitProvider
  fetchAccessToken={fetchAccessToken}
  onReceivedAdditionalMetadata={(metadata) => {
    console.log('Received from SDK:', metadata);
    // Handle partner-specific events or data
  }}
>
  <YourApp />
</TaxKitProvider>
```

元数据为 `Record<string, unknown>` 允许灵活的特定伙伴执行而不改变SDK.

### URL 参数元数据

SDK还支持通过合作伙伴应用程序上的URL参数来传递元数据. 添加一个 `cointracker-tax-kit-param` 查询参数到您的页面 URL, SDK 将自动将其纳入元数据 :

```
https://your-partner-site.com/tax-center?cointracker-tax-kit-param=my-value
```

## 特征

-   交易管理和跟踪
-   与各种交换机和钱包合并
-   成本计算
-   税务表生成支持

## 错误代码

TaxKit 提供了可以通过 `error` 归还的财产 `useTaxKit` 钩. 这些错误帮助您处理应用程序中不同的故障情况 .

### 一般税基错误

这些错误可通过 `TaxKitError` enum并代表高级 SDK 状态错误 :

-   **`generic_error`** - 发生了一般错误
-   **`missing_connections`** - 没有为用户配置连接
-   **`connection_sync_errors`** - 一个或多个连接有同步错误
-   **`transactions_needs_review`** - 交易需要人工审查
-   **`authentication_error`** - 认证失败(例如无效或过期的访问符)

### 示例使用

```tsx
import { useTaxKit, TaxKitError } from '@cointracker/tax-kit';

function YourComponent() {
  const { error } = useTaxKit();

  if (error) {
    // Check error codes using the TaxKitError enum
    switch (error) {
      case TaxKitError.MissingConnections:
        return <p>Please connect an exchange or wallet to get started.</p>;
      case TaxKitError.AuthenticationError:
        return <p>Authentication failed. Please try again.</p>;
      case TaxKitError.ConnectionSyncErrors:
        return (
          <p>
            Some connections have sync errors. Please check your connections.
          </p>
        );
      case TaxKitError.TransactionsNeedsReview:
        return (
          <p>Some transactions require review before they can be processed.</p>
        );
      default:
        return <p>An error occurred: {error}</p>;
    }
  }

  return <div>TaxKit is ready</div>;
}
```

## 从平面道具形状移走

2.2.0版本中平面道具形状被重组为分组子对象. 旧道具仍然在工作 并被映射到新的形状内部, 但每个记录a `console.warn` 每个浏览器会话一次,并将在未来的主要版本被删除.

| 旧道具 | 新地点 |
| --- | --- |
| `apiBaseUrl` | `options.apiBaseUrl` |
| `hostPageUrl` | `options.hostPageUrl` |
| `mode` | `options.mode` |
| `flow` | `options.flow` |
| `overlayMode` | `options.overlayMode` |
| `defaultOpen` | `options.defaultOpen` |
| `hideNavigationBar` | `options.hideNavigationBar` |
| `hideBackButton` | `options.hideBackButton` |
| `helpLinkUrl` | `options.helpLinkUrl` |
| `themeContract` | `theme.light` 编号 : `theme.dark` |
| `themeMode` | `theme.mode` |
| `userPromoCode` | `metadata.promoCode` |

当一新旧道具被通过时,新形状会取胜. 过 `null` 改为 `metadata.promoCode` 明确阐明一种价值,而不是回到遗留的道具.

### 2.2.0中删除: `partnerCostBasisMethodsByYear` 道具

这个 `partnerCostBasisMethodsByYear` 道具及其相机被完全拆除。 奉献 `Record<number, CostBasisMethod>` 管道的建造是推测的,每年执行成本基准,但从未使用过UI部件。 合作伙伴(书面确认)通过 `metadata.costBasisMethodInfo` 相反,iframe实际上读取的另一种密钥(`CostBasisMethodMismatchWarningOverlay.tsx`) (中文(简体) ). 需要通过基于成本的元数据的伙伴应继续使用 `metadata.costBasisMethodInfo` 或其他自定义密钥.

### 2.2.0中删除: `startRoute` 螺旋桨和 `?startRoute=` URL 转发

两者 `startRoute` 道具和电线 `?startRoute=` URL转发被移除 。 调查显示,这一特性实际上在生产中是禁用:iframe上由犬类状态驱动的路由 `startRoute` 除一个具体案件外,其他所有案件`/checkout-complete`iframe 向它过渡 通过内部x状态事件 之后的支付。 通过的合伙人 `startRoute` 支付一个功能 它实际上不是导航 用户任何地方.

如果一个真正的深层连接需要水面后出现,我们就会设计并把它作为适当的特征来运输.

### 2.2.0中删除: `themeClassName` 道具

这个 `themeClassName` 道具被移除了。 iframe的包装器现在直接从 `theme.mode` ——合伙人不再需要考虑Tailwind自定义变体或通过任何课程Name.

为什么改变是安全的:

-   Iframe SDK的捆绑CSS有 **零** 尾风公用事业 `ct-embedded-dark:*` 或者说 `pro:*` 自定义变体——这些变体声明是存在的,但从未与任何效用类别相匹配,因此,价值如下: `'ct-embedded-dark'` 或者说 `'pro dark'` 在iframe内部没有任何意义.
-   功能上重要的作品——提供 `.dark` 祖宗是基辅的 `dark:*` 尾风公用设施可起火——现在通过应用 `theme.mode` (例如:. `'dark'`直接到 iframe 的包装.
-   这个 **父应用程序** 自己的主题类Name 机制( 用于父侧的负载) `pro:*` 水电费 `apps/embedded-api/app/`)是完全独立的,不受这一变化的影响.

先前通过的伙伴 `themeClassName` 应取去. 无需替换—— `theme.mode` 覆盖唯一 道具实际做的 在iframe.

### 2.2.0中删除: `overridePartnerLogo` 道具

这个 `overridePartnerLogo` 道具被移除了。 iframe现在直接从JWT衍生的伙伴身份中解决伙伴的标志(Iframe)`embeddedHealth.partnerId`通过 Iframe 的图标注册。 如果JWT将您的整合确定为 `'kraken'`, (中文(简体) ), `'coinbase'`等,匹配的标志会自动渲染.

**更新于2.3.0:** 如果您是新搭档,且在 Iframe 的注册中没有硬编码的 SVG, 请直接通过您的标志 URL [`theme.partnerLogo`](https://npmcn.com/package/%40cointracker/tax-kit/#readme-partner-branding-logo-and-fonts) ——无需修改CoinTracker-side代码. 硬编码登记册仍然是生产伙伴(Coinbase、Kraken)的倒置.

## 许可证

ISC - 版权追踪器

## 常见问题

### @cointracker/tax-kit 是什么？

提供成本基础数据的硬跟踪器SDK

### 如何安装 @cointracker/tax-kit？

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

### @cointracker/tax-kit 支持 TypeScript 吗？

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

### @cointracker/tax-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cointracker/tax-kit 可以商用吗？

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

### @cointracker/tax-kit 的下载量有多少？

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

### @cointracker/tax-kit 还在维护吗？

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