SDK Structure

The PaymentKit Node.js SDK is built on a modular, resource-oriented architecture. This design ensures that interactions with different parts of the PaymentKit API are consistent, predictable, and robust. At its core, the SDK uses a central utility to generate methods for each API resource (like Customers, Products, etc.), which handles all communication with the underlying PaymentKit Blocklet.

This structure abstracts away the complexities of inter-component communication, allowing you to focus on your application's business logic.


The Resource Factory#

Each resource exposed by the SDK (e.g., products, customers, subscriptions) is a collection of methods generated by a central factory. This factory pattern ensures that all API methods share a consistent signature and behavior. The primary functions responsible for this are createResourceMethod and createResourceCreateMethod.

These factories take a specification that defines the HTTP method and API path, and return an asynchronous function that handles the full request lifecycle.

Here is a conceptual look at how the products resource is constructed internally:

Conceptual Example

import { createResourceMethod, createResourceCreateMethod } from './resource';

// This is a simplified example to illustrate the pattern.
const products = {
  // Method for creating a new resource
  create: createResourceCreateMethod({ method: 'POST', path: '/v1/products' }),

  // Methods for retrieving, updating, listing, and deleting
  retrieve: createResourceMethod({ method: 'GET', path: '/v1/products/{id}' }),
  update: createResourceMethod({ method: 'PUT', path: '/v1/products/{id}' }),
  list: createResourceMethod({ method: 'GET', path: '/v1/products' }),
  del: createResourceMethod({ method: 'DELETE', path: '/v1/products/{id}' }),
};

This approach allows the SDK to be easily maintained and extended while providing a uniform developer experience across all API endpoints.

Automatic Component Handling#

Before any API request is sent, the SDK automatically ensures that the PaymentKit Blocklet is running and available. This is managed by the ensureComponentRunning utility.

When you call an SDK method:

  1. The SDK first checks the status of the PaymentKit component.
  2. If the component is not running, it will wait for it to start.
  3. Once the component is confirmed to be running, the API request is dispatched.
  4. If the component fails to start, the method call will throw an error.

This built-in check removes the burden of manually managing the PaymentKit component's lifecycle from your application code, preventing common errors and race conditions.

All communication is ultimately handled by the @blocklet/sdk's component.call function, which provides the low-level mechanism for secure, inter-blocklet communication.

Seamless Environment Management#

The resource factories also automatically inject the livemode parameter into every API request based on the SDK's current configuration. Whether you are operating in live or test mode, the SDK handles passing the correct parameter to the PaymentKit API without any extra effort on your part.

This means you can switch between environments with a single configuration change, and all subsequent API calls will be routed correctly.

Getting Started
Environments