TypeScript 支持
PaymentKit Node.js SDK 完全使用 TypeScript 开发，为所有 API 资源和方法提供了全面的类型定义。这种集成通过启用自动补全、编译时错误检查以及更清晰、自文档化的代码，提供了卓越的开发体验。
通过类型定义增强开发#
所有 API 资源都有对应的 TypeScript 类型，你可以直接导入它们，以在你的应用中实现强大的类型安全。这消除了在处理 API 响应时的猜测，并减少了常见错误。
例如，你可以导入 TSubscription 类型来处理订阅对象：
import { TSubscription } from '@blocklet/payment-js';
function processSubscription(sub: TSubscription) {
console.log(`Subscription ${sub.id} is currently ${sub.status}.`);
}利用扩展类型#
许多 SDK 方法返回“扩展”对象，这些对象在单个 API 响应中包含了相关资源。为此，SDK 提供了 Expanded 类型（例如 TSubscriptionExpanded）。这些类型特别有用，因为它们为嵌套对象（如订阅的客户或其订单项）提供了完整的类型信息。
例如，TSubscriptionExpanded 类型包括完整的 TCustomer 对象和 TSubscriptionItemExpanded 对象数组。
// A simplified view of the TSubscriptionExpanded type
export type TSubscriptionExpanded = TSubscription & {
object: 'subscription';
customer: TCustomer;
paymentCurrency: TPaymentCurrency;
paymentMethod: TPaymentMethod;
items: TSubscriptionItemExpanded[];
serviceType: 'credit' | 'standard';
};实践示例：自动补全与安全性#
得益于 TypeScript 的类型推断功能，你通常不需要手动注解类型。该 SDK 的设计使得其方法的返回类型能够被自动推断，从而在你的编辑器中可以立即使用自动补全和类型检查功能。
import payment from '@blocklet/payment-js';
async function getSubscriptionDetails(subscriptionId) {
try {
// The 'subscription' constant is automatically typed as TSubscriptionExpanded
const subscription = await payment.subscriptions.retrieve(subscriptionId);
// Access properties with full autocompletion and type safety
console.log(`Customer ID: ${subscription.customer.id}`);
console.log(`Service Type: ${subscription.serviceType}`);
subscription.items.forEach(item => {
console.log(`- Item: ${item.price.product.name}, Price: ${item.price.unit_amount}`);
});
} catch (error) {
console.error('An error occurred:', error.message);
}
}
getProductDetails('sub_xxx');在此示例中，你的 IDE 会知道 subscription.customer 具有 id 属性，并且 subscription.items 是一个数组，其中每个元素都包含一个嵌套的 price 对象。
可用数据模型#
该 SDK 为所有主要 API 资源都公开了类型。以下是一些你可以使用的关键模型：
模型名称 | 描述 |
|---|---|
| 代表用于支付处理的结账会话。 |
| 代表客户对象。 |
| 定义产品的定价。 |
| 代表你提供的商品或服务。 |
| 管理客户的周期性付款。 |
| 跟踪单次支付的生命周期。 |
| 跟踪基于信用的计费使用情况。 |
| 代表向客户发放的信用额度。 |
| 记录客户信用余额的交易。 |
| 配置用于接收事件通知的端点。 |
通过利用这些内置类型，你可以构建更可靠、更易于维护的支付集成。要查看这些类型的实际应用，请浏览详细的 API 参考。