TypeScript Support
The PaymentKit Node.js SDK is developed entirely in TypeScript, providing comprehensive type definitions for all API resources and methods. This integration offers a superior development experience by enabling autocompletion, compile-time error checking, and clearer, self-documenting code.
Enhanced Development with Type Definitions#
All API resources have corresponding TypeScript types, which you can import directly for robust type safety in your application. This eliminates guesswork and reduces common errors when handling API responses.
For example, you can import the TSubscription type to work with subscription objects:
import { TSubscription } from '@blocklet/payment-js';
function processSubscription(sub: TSubscription) {
console.log(`Subscription ${sub.id} is currently ${sub.status}.`);
}Leveraging Expanded Types#
Many SDK methods return "expanded" objects, which include related resources in a single API response. For these, the SDK provides Expanded types (e.g., TSubscriptionExpanded). These types are particularly useful as they provide full type information for nested objects, such as a subscription's customer or its line items.
For instance, the TSubscriptionExpanded type includes the full TCustomer object and an array of TSubscriptionItemExpanded objects.
// A simplified view of the TSubscriptionExpanded type
export type TSubscriptionExpanded = TSubscription & {
object: 'subscription';
customer: TCustomer;
paymentCurrency: TPaymentCurrency;
paymentMethod: TPaymentMethod;
items: TSubscriptionItemExpanded[];
serviceType: 'credit' | 'standard';
};Practical Example: Autocompletion and Safety#
Thanks to TypeScript's type inference, you often don't need to annotate types manually. The SDK is designed so that the return types of its methods are automatically inferred, providing immediate access to autocompletion and type checking in your editor.
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');In this example, your IDE would know that subscription.customer has an id property and that subscription.items is an array where each element contains a nested price object.
Available Data Models#
The SDK exposes types for all major API resources. Here are some of the key models you can work with:
Model Name | Description |
|---|---|
| Represents a checkout session for payment processing. |
| Represents a customer object. |
| Defines the pricing for a product. |
| Represents a good or service you offer. |
| Manages recurring payments for a customer. |
| Tracks the lifecycle of a single payment. |
| Tracks usage for credit-based billing. |
| Represents credits issued to a customer. |
| Records a transaction against a customer's credit balance. |
| Configures endpoints to receive event notifications. |
By leveraging these built-in types, you can build more reliable and maintainable payment integrations. To see these types in action, explore the detailed API Reference.