SDK Structure
The PaymentKit Node.js SDK is designed as a streamlined and reliable bridge to the PaymentKit component's API. Instead of containing manually-written methods for every API endpoint, its architecture is built around a set of core utilities that dynamically generate resource methods and manage the connection state. This approach ensures consistency across the SDK and simplifies maintenance.
The following diagram illustrates the typical flow when you call an SDK method:
Resource Method Factories#
The core of the SDK's design is a pair of factory functions, createResourceMethod and createResourceCreateMethod, located in the central resource utility. These factories generate the standard API methods (e.g., create, retrieve, update, list, del) for each resource based on a simple configuration object.
This configuration, MethodSpec, defines the HTTP method and the API path for an endpoint:
type MethodSpec = {
method: 'GET' | 'POST' | 'PUT' | 'DELETE';
path: string;
};A resource method, such as retrieving a customer, is generated by passing a MethodSpec to the factory. The factory returns a function that handles parameter mapping, connection management, and the final API call.
// This is a conceptual example of how a resource method is created internally
import { createResourceMethod } from './resource';
const retrieveCustomer = createResourceMethod<Customer, void, string>({
method: 'GET',
path: '/v1/customers/{id}', // Path placeholder {id} is automatically replaced
});
// Calling retrieveCustomer('cust_123') now triggers the full API call flow.This pattern eliminates repetitive boilerplate code and ensures that all resource methods behave consistently.
Component Communication#
The SDK does not make direct HTTP requests to the PaymentKit API. Instead, it communicates through the Blocklet SDK's component.call function. This function facilitates secure and efficient inter-component communication within the Blocklet Server environment.
All calls are directed to the Payment Kit component using its unique identifier, PAYMENT_KIT_DID (z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk). This internal communication is managed automatically by the SDK.
Connection Management#
To ensure reliability, every API call is preceded by a check to confirm the PaymentKit component is running. The ensureComponentRunning function handles this process:
- It first checks the current status of the Payment Kit component using
isPaymentRunning(). - If the component is not running, it pauses execution and waits for the component to start.
- Once the component is running, the original API call proceeds.
This automatic check prevents runtime errors and abstracts the complexity of managing service availability from the developer.
For scenarios where you need to run initialization logic only after the Payment Kit is ready, the SDK provides the ensureStart utility:
import payment from '@blocklet/payment-js';
// This function will only execute after the Payment Kit component is confirmed to be running.
payment.ensureStart(async () => {
console.log('Payment Kit is ready. Performing initial setup.');
// e.g., Fetch initial settings or configurations
const settings = await payment.settings.retrieve();
console.log('Initial settings loaded:', settings);
});Unified SDK Object#
The main index.ts file serves as the entry point for the SDK. It imports all the individual resource modules (e.g., customers, products, subscriptions) and assembles them into a single, structured object. This provides a clean and intuitive interface for developers.
import payment from '@blocklet/payment-js';
// Access different resources via the main export
payment.customers.create(...);
payment.products.list(...);
payment.checkout.sessions.create(...);
// Access utility functions
payment.isPaymentRunning();
payment.environments.setLivemode(true);This architecture provides a clear separation of concerns, with resource-specific logic isolated in its own module while core functionality is centralized.
Now that you understand how the SDK is structured, the next step is to learn how to configure it for different development stages. Proceed to the Environments section to manage test and live modes.