@ cointracker/ tax- kit

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

安装

npm install @cointracker/tax-kit

使用量

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数字 :

<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( 两种模式都使用) 或每个模式对象 :

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

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。 。 。 .

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 子设置和格式谈判.

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

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数字 :

<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() 继续全应用程序工作 :

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

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

保留密钥

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

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

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

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

从 SDK 接收元数据

SDK 可以使用 onReceivedAdditionalMetadata 回调 :

<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 - 认证失败(例如无效或过期的访问符)

示例使用

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 每个浏览器会话一次,并将在未来的主要版本被删除.

当一新旧道具被通过时,新形状会取胜. 过 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-completeiframe 向它过渡 通过内部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 ——无需修改CoinTracker-side代码. 硬编码登记册仍然是生产伙伴(Coinbase、Kraken)的倒置.

许可证

ISC - 版权追踪器