# @doola/js 中文文档

规范地址：https://npmcn.com/package/%40doola/js/

版本：0\.3\.0
npm 元数据更新时间：2026-10-08T17:20:41.946Z
中文译文更新时间：2026-11-12T16:28:41.519Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40doola/js
原文对照：https://npmcn.com/package/%40doola/js/?lang=original
项目主页：https://github.com/doolahq/doola-js/tree/main/packages/js#readme
源码仓库：https://github.com/doolahq/doola-js

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

- 包体积（解压后）：96.8 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-09-23T17:40:06.207Z
- 最新版本发布：2026-10-08T17:20:41.525Z
- 近 30 天下载量：4271（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

装入器, TypeScript 类型和一个服务器会话帮助器, 用于在您的产品中嵌入 doola 组装 .

## 安装

```sh
npm install @doola/js
```

也可以使用：`pnpm add @doola/js`、`yarn add @doola/js`、`bun add @doola/js`

## README

# @doola/js (英语)

[![npm](https://img.shields.io/npm/v/@doola/js)](https://www.npmjs.com/package/@doola/js) [![CI](https://github.com/doolahq/doola-js/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/doolahq/doola-js/actions/workflows/ci.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/doolahq/doola-js/badge)](https://scorecard.dev/viewer/?uri=github.com/doolahq/doola-js) [![license](https://img.shields.io/npm/l/@doola/js)](https://github.com/doolahq/doola-js/blob/main/LICENSE)

嵌入 [杜拉语name](https://www.doola.com/) 你的产品是美国公司 您的客户表 专卖中心或C公司,在您的应用程序和 在你的品牌下.

这个包是故意小的(在 1 KB gziped 下),没有UI. 装上多拉的 版本装入器 `js.doola.com`,它搭载了从 `sdk.doola.com`每一个 屏幕、字段和验证都生活在这个框架内:

-   **敏感数据从不触及你的代码.** SSN、ITIN和签名被打入多拉的 并且被送到了Doola的API。 它们从未出现在您的 JavaScript, 您的错误跟踪器, 您的 会话重放或您的日志 .
-   **你从不为我们的改变而重新部署.** 国家要求、IRS表格和UI改进船 在iframe内。 这个软件包固定了呼叫的形状,从来就没有它背后的行为.

**完整文档: [docs.doola.com/sdk 页面存档备份,存于互联网档案馆](https://docs.doola.com/sdk/overview)。 。 。 .** 此页面为 短版本:安装,三步并多读到何处.

## 如何融为一体

1.  **您的服务器** 使用您的密钥为注册客户提供短寿命的薄荷会话.
2.  **您的页面** 电话 `loadDoola()` 并附加它创建的元素。 顾客完成 iframe内部的阵型向导.
3.  **提交时** 你会得到 `onFormed({ companyId })`。你在自己的离职单和你的 服务器确认为 Doola 。 没有档案,没有花费 直到你这样做.

## 在你开始之前

你需要两把钥匙。 可公布的密钥选择浏览器的环境和秘诀 键在您的服务器上也这样做.

| 密钥 | 前缀 | 它的栖息地点 | 如何获得它 |
| --- | --- | --- | --- |
| 可出版 | `pk_test_` 或者说 `pk_live_` | 你的前门 设计公开. | [伙伴门户](https://partners-portal.doola.com/)下页 **SDK 软件**,则 **安装**它识别你并选择你的品牌. |
| 秘诀 | `dk_test_` 或者说 `dk_live_` | 只有你的服务器 永远不要在浏览器或捆绑中. | [伙伴门户](https://partners-portal.doola.com/)下页 **设置**,则 **API 密钥**。 。 。 . |

测试和活性是独立的堆栈,有独立的数据. 使用匹配对 :

| 环境 | 密钥 | 合作伙伴 API | 嵌入式应用程序 |
| --- | --- | --- | --- |
| 测试 | `pk_test_`, (中文(简体) ), `dk_test_` | `https://api.test.doola.com` | `https://sdk.test.doola.com` |
| 现场直播 | `pk_live_`, (中文(简体) ), `dk_live_` | `https://api.doola.com` | `https://sdk.doola.com` |

## 安装

```bash
npm install @doola/js
```

包含类型脚本。 一揽子措施是无害环境管理和共同JS,有两个切入点: `@doola/js` 仅在浏览器中运行,以及 `@doola/js/server` 运行在您的服务器上, 在节点 18 或 18 或 任何 使用网络标准的运行时间 `fetch`。 。 。 .

## 1\. 在您的服务器上装入一个会话

你的服务器是你秘密钥匙生活的唯一地点 添加一个认证的路由 [创建客户会话](https://docs.doola.com/api/api-reference/customer-sessions/create-a-customer-session) 给签到的客户。 它不需要数据库. `createSessionHandler` 构建路径: 它 使用网络标准 `Request` 返回 a `Response`。这使得它成为一个 Next.js 路由处理器 和在Remix中装有一行的包装器(`action`霍诺 邦 德诺 和克云弗莱尔工人, 地点 `process.env` 需求 `nodejs_compat` 旗帜.

```ts
// POST /doola-session
import { createSessionHandler } from '@doola/js/server';

export const POST = createSessionHandler({
  // Your dk_ secret key. Its prefix selects the API host. A missing key is refused per
  // request, so `next build` passes without it, and a pk_ key throws here.
  apiKey: process.env.DOOLA_API_KEY,

  // Return null when nobody is signed in. The route answers 401, and the loader reports
  // partner_session_expired.
  getCustomer: async (request) => {
    const user = await getSignedInUser(request); // your own auth
    // externalCustomerId is optional but recommended: it is matched before the email, so a
    // customer who changes their email with you stays the same doola customer.
    return user ? { email: user.email, externalCustomerId: user.id } : null;
  },

  // The browser gets the status, plus doola's error code when doola refused the customer.
  // This says why, for your logs: a revoked key, an outage, or a field doola rejected.
  onFailure: (failure) => console.error('doola session failed', failure),
});
```

该标志就是一个客户,在几分钟内失效。 装填器再次呼叫您的路线 更新它,所以杜拉会话 永远不会超过你的登录。 保护路线与其它路线一样 认证 `POST`包括你的CSRF保护.

快取、快取和其他语言: [创建会话](https://docs.doola.com/sdk/sessions)。 。 。 .

## 2\. 在浏览器中挂载

```ts
import { loadDoola } from '@doola/js';

const doola = await loadDoola({
  publishableKey: 'pk_live_…',

  // Called on mount, on every renewal and on Try again. Always fetch a fresh session.
  fetchAccessToken: async () => {
    const r = await fetch('/doola-session', { method: 'POST' });
    if (!r.ok) {
      // Reject with the status and doola's error code: the loader maps them to error types.
      const { code } = await r.json().catch(() => ({}));
      throw Object.assign(new Error('doola session'), { status: r.status, code });
    }
    return r.json();
  },

  // Can fire more than once, so keep it idempotent.
  onAuthError: (error) => {
    if (error.type === 'partner_session_expired') location.assign('/login');
    if (error.type === 'email_in_use' || error.type === 'customer_revoked') showSupportMessage();
    // Your mapping between users and externalCustomerId, not the customer's to fix.
    if (error.type === 'external_id_conflict') console.error('doola session conflict', error);
  },

  // The customer submitted the wizard. Start your checkout for this company.
  onFormed: ({ companyId }) => startCheckout(companyId),
});

// Mount into an element on your page: <div id="doola"></div>
const element = doola.create();
document.getElementById('doola')!.append(element);
```

`create()` 没有争论。 应用程序决定从客户状态显示什么:巫师 对于新客户,他们的公司一旦存在.

每页保留一个实例: 选项由第一个选项固定 `loadDoola()` 电话 框架, 电话上的签名和全屏模式 : [装入了SDK](https://docs.doola.com/sdk/embed)。 。 。 .

## 3\. 接受付款,然后确认

`onFormed` 故意给你公司身份证明 而不是别的 任何送到你身边的东西 页面的JavaScript可以在 DevTools 中被编辑,所以您的服务器可以处理欠下的内容. 当你 退出开始 :

1.  **把公司找来** 用您的密钥, 使用 [找一个公司](https://docs.doola.com/api/api-reference/companies/get-a-company)。仅装入 时 `formationSubmissionStatus` 实值 `AWAITING_PAYMENT`。 。 。 .
2.  **检查它属于注册客户.** 通过公司 `doolaCustomerId` 改为 [找一个客人](https://docs.doola.com/api/api-reference/customers/get-a-customer) 比较 页:1 `email`。 。 。 .
3.  **在您的服务器上定价** 从公司 `state`, (中文(简体) ), `entityType` 页:1 `services`, (中文(简体) ), 加上国家收费 [列出国家申报费](https://docs.doola.com/api/api-reference/reference-data/list-state-filing-fees)。 。 。 . 从未从浏览器读取价格 .
4.  **充电,然后确认** 与 [确认付款](https://docs.doola.com/api/api-reference/companies/confirm-payment-for-a-draft-formation)。 。 。 . 在你做之前,任何文件都不会归档:

```ts
// On your server, after the charge succeeds.
const DOOLA_API = 'https://api.doola.com'; // https://api.test.doola.com with a dk_test_ key

function doolaKey(): string {
  const key = process.env.DOOLA_API_KEY; // your dk_ secret key
  if (!key) throw new Error('DOOLA_API_KEY is not set');

  return key;
}

async function confirmPayment(companyId: string, paymentReference: string): Promise<void> {
  const path = `/v1/partner/companies/${encodeURIComponent(companyId)}/payment-confirmed`;

  const r = await fetch(`${DOOLA_API}${path}`, {
    method: 'POST',
    headers: { authorization: doolaKey(), 'content-type': 'application/json' },
    // Your own reference (a payment intent id, an order id). Logged, never verified.
    body: JSON.stringify({ partnerReference: paymentReference }),
  });

  // Idempotent, so a failed call is safe to retry.
  if (!r.ok) throw new Error(`doola payment-confirmed failed with ${r.status}`);
}
```

`onFormed` 例如当创始人回到一个没有报酬的公司时 组织起来并要求支付。 按键命令 `companyId` 所以你从不收两次钱.

在您确认后, 替换您安装在步骤 2: `element.replaceWith(doola.create())`。 。 。 . 它的支付屏幕不监视您的确认, 所以只有一个新元素显示创建者 他们的公司。 每个 `create()` 是一个单独的iframe, 所以永远不要在旧的旁边附加第二个. 从那时起,合伙人API [网络用户](https://docs.doola.com/api/webhooks) 告诉你如何 阵型开始.

边际案件、退款及对账: [收钱](https://docs.doola.com/sdk/payments)。 。 。 .

## 文档

| 读取 | 对于 |
| --- | --- |
| [快速启动](https://docs.doola.com/sdk/quickstart) | 工作嵌入和测试费大约15分钟 |
| [如何运作](https://docs.doola.com/sdk/how-it-works) | 关键、会话和形成周期 |
| [收钱](https://docs.doola.com/sdk/payments) | 您的离职,确认电话和每一个边缘案件 |
| [客户参考](https://docs.doola.com/sdk/reference/client) | 每一个选项、方法和召回 |
| [服务器参考](https://docs.doola.com/sdk/reference/server) | `@doola/js/server` 和合作伙伴 API 结尾 |
| [错误](https://docs.doola.com/sdk/reference/errors) | `onAuthError`, (中文(简体) ), `onLoadError` 和怎么办 每一个 |
| [安全和数据](https://docs.doola.com/sdk/security) | 内容安全政策、信任类型和数据流动 |
| [测试](https://docs.doola.com/sdk/testing) | 测试环境和沙盒游乐场 |
| [启用清单](https://docs.doola.com/sdk/go-live) | 所有要检查的,在直播键之前 |
| [合作伙伴 API](https://docs.doola.com/api/introduction) | 支付后需采取的行动 |

## 版本

`@doola/js` 随取出 [更改日志](https://github.com/doolahq/doola-js/blob/main/packages/js/CHANGELOG.md) 列表中 释放。 装载器在 `js.doola.com/v1` 更新并保持与每个 `@doola/js` 释放在主, 所以修复到达你的站点 不升级或部署.

## 支助和安全

-   问题: [工程学@ doola.com](mailto:engineering@doola.com),或见 [支助](https://github.com/doolahq/doola-js/blob/main/SUPPORT.md)。 。 。 .
-   如本报告所述,私下报告脆弱性 [警卫](https://github.com/doolahq/doola-js/blob/main/SECURITY.md)从不公开 问题.

## 许可证

[麻省理工学院](https://github.com/doolahq/doola-js/blob/main/LICENSE)

## 常见问题

### @doola/js 是什么？

装入器, TypeScript 类型和一个服务器会话帮助器, 用于在您的产品中嵌入 doola 组装 \.

### 如何安装 @doola/js？

在项目目录运行 npm install @doola/js，或使用 pnpm add / yarn add / bun add。

### @doola/js 支持 TypeScript 吗？

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

### @doola/js 支持 ESM 还是 CommonJS？

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

### @doola/js 可以商用吗？

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

### @doola/js 的下载量有多少？

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

### @doola/js 还在维护吗？

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