# hasapla 中文文档

规范地址：https://npmcn.com/package/hasapla/

版本：0\.1\.9
npm 元数据更新时间：2026-11-03T19:38:38.237Z
中文译文更新时间：2026-11-03T19:59:01.158Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/hasapla
原文对照：https://npmcn.com/package/hasapla/?lang=original

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

- 包体积（解压后）：57.1 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-08-24T15:12:04.153Z
- 最新版本发布：2026-11-03T19:38:38.086Z
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Hasapla的TypeScript SDK， AI公司的计费平台

## 安装

```sh
npm install hasapla
```

也可以使用：`pnpm add hasapla`、`yarn add hasapla`、`bun add hasapla`

## README

# Hasapla Node.js SDK

的官方TypeScript SDK [Hasapla](https://hasapla.com/)这是人工智能公司的计费平台。

对Node.js 18及更新版本的客户余额、客户、组织、特性、计划、订阅和使用事件的类型访问。

## 安装

```sh
npm install hasapla
```

## 初始化

创建一个客户机，并在整个服务器应用程序中重用它。将API密钥保存在服务器上。

```ts
import { Hasapla } from "hasapla";

const hasapla = new Hasapla({
    apiKey: process.env.HASAPLA_API_KEY!,
});
```

## 平衡

```ts
const balance = await hasapla.balance.get({
    extCustomerId: "customer-123",
});
// { balance: 3000, unlimited: false }
```

只提供其中一个 `extCustomerId` 或 `extOrganizationId`． SDK将这些映射到API `ext_customer_id` 和 `ext_organization_id` 查询参数。无限订阅回报 `{ balance: null, unlimited: true }`;待定的有限订阅返回零。此端点不授权使用或刷新过期期限。

这将取代之前的占位符：结果现在是一个对象而不是一个数字，并且无限余额是 `null` 而不是 `-1`。

## 客户

```ts
await hasapla.customers.create({
    email: "customer@example.com",
    name: "Example Customer",
    extCustomerId: "customer-123",
});
```

## 订阅

为客户或组织订阅一个计划。只提供其中一个 `customer_uuid` 或 `organization_uuid` 间隔为 `"month"` 或 `"year"`。

```ts
const subscription = await hasapla.subscriptions.subscribe({
    customer_uuid: "customer-uuid",
    plan_uuid: "plan-uuid",
    interval: "month",
});
```

免费计划立即激活。付费计划仍然悬而未决，没有期限日期和信用授予。间隔不会选择不同的目录价格。订阅字段使用API的snake\_case名称。

查看客户当前的订阅：

```ts
const subscriptions = await hasapla.subscriptions.list({
    customer_uuid: "customer-uuid",
    current: true,
});
```

使用 `organization_uuid` 对于一个组织来说。结果是一个数组，它可以是空的。省略 `current` 包括历史订阅。分页接受 `limit` （1-1000，默认100）和 `offset` 0(默认)。

通过UUID检索订阅：

```ts
const subscription = await hasapla.subscriptions.get("subscription-uuid");
```

立即改变计划或间隔：

```ts
const replacement = await hasapla.subscriptions.change("subscription-uuid", {
    plan_uuid: "target-plan-uuid",
    interval: "month",
    activate_immediately: true,
    payment_reference_id: "verified-payment-reference",
    amount: 3000,
    currency: "USD",
});
```

对于付费目标，首先在服务器上验证付款，并提供完整的目标价格和货币。对于免费目标，省略所有三个支付字段。相同间隔的更改保留续订日期，除非从免费转为付费；间隔更改开始一个新的时间段。匹配重试将返回现有的后继程序，选择相同的计划和间隔不会进行任何更改。计划更改(`activate_immediately: false`)当前返回HTTP 409。

## 使用事件

```ts
await hasapla.events.create({
    extCustomerId: "customer-123",
    featureKey: "api_call",
});
```

在执行工作之前保留一个事件，然后在成功时捕获它，否则释放它：

```ts
const reservation = await hasapla.events.reserve({
    extCustomerId: "customer-123",
    featureKey: "api_call",
});

if (!reservation.key) {
    throw new Error("Reservation key is missing");
}

try {
    await performWork();
    await hasapla.events.capture({ key: reservation.key });
} catch (error) {
    await hasapla.events.release({ key: reservation.key });
    throw error;
}
```

当客户用完功能限额时， `reserve` 抛出一个 `409` 可以检查的错误 `isFeatureLimitReachedError`：

```ts
import { isFeatureLimitReachedError } from "hasapla";

try {
    await hasapla.events.reserve({
        extCustomerId: "customer-123",
        featureKey: "api_call",
    });
} catch (error) {
    if (isFeatureLimitReachedError(error)) {
        console.error("Feature limit reached");
    } else {
        throw error;
    }
}
```

## 错误

API响应失败抛出 `HasaplaError` 使用HTTP状态和解析后的响应体。

```ts
import { HasaplaError } from "hasapla";

try {
    await hasapla.customers.get({ externalId: "missing-customer" });
} catch (error) {
    if (error instanceof HasaplaError) {
        console.error(error.status, error.body);
    }

    throw error;
}
```

## 许可证

apache - 2.0

## 常见问题

### hasapla 是什么？

Hasapla的TypeScript SDK， AI公司的计费平台

### 如何安装 hasapla？

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

### hasapla 支持 TypeScript 吗？

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

### hasapla 支持 ESM 还是 CommonJS？

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

### hasapla 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### hasapla 可以商用吗？

hasapla 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### hasapla 还在维护吗？

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