Core SDK Concepts

The SumUp Node.js SDK is built upon several core concepts and fundamental building blocks that streamline interactions with the SumUp API. These elements provide a structured, type-safe, and developer-friendly experience for integrating SumUp's functionalities into your applications. For an overall understanding of the SDK's purpose and features, refer to the [Overview] page.

Here are the key concepts underpinning the SDK:

APIResource Base Class

The APIResource is a foundational class that serves as the parent for all specific API resource client classes within the SDK (e.g., Checkouts, Merchant, Readers). Its primary role is to provide a common structure and enable each resource class to access the main SumUp HTTP client. By inheriting from APIResource, each resource class gains the ability to make API requests through the client, ensuring consistency in how different parts of the SumUp API are accessed and managed. This abstraction helps in organizing the API into logical domains and keeps the code DRY (Don't Repeat Yourself).

APIPromise Wrapper

APIPromise is a custom wrapper that enhances the standard JavaScript Promise object, specifically designed for handling asynchronous API operations. When you make an API call using the SDK, it returns an APIPromise instance. This wrapper encapsulates the raw Promise<Response> returned by the underlying fetch mechanism.

It provides two crucial methods for convenience:

• parse(): This method handles the parsing of the HTTP response body, typically deserializing JSON data into the expected TypeScript type.
• withResponse(): This method allows you to retrieve both the parsed data and the raw Response object from the HTTP call, which can be useful for inspecting HTTP headers, status codes, or other response details directly.

By implementing the standard then, catch, and finally methods, APIPromise behaves like a native Promise, allowing you to use async/await syntax for cleaner asynchronous code, while offering additional utility for API responses.

APIError for Error Handling

The APIError class is a specialized error type used by the SDK to provide detailed information when an API request fails (e.g., receives an HTTP status code of 4xx or 5xx). It extends a base SumUpError and encapsulates critical information about the failed request:

• status: The HTTP status code of the response (e.g., 400, 404, 500).
• error: The error body returned by the API, which can be a parsed JSON object or a raw string message.
• response: The raw Response object from the fetch call, offering full access to the HTTP response details.

This structured error handling allows developers to programmatically inspect the nature of an API failure, making it easier to implement robust error recovery and user feedback mechanisms.

FetchParams for Request Customization

FetchParams is a type definition that represents a subset of the standard RequestInit options available in the browser's fetch API. It specifically omits body and method, as these are typically handled by the SDK's generated methods.

This type is exposed as an optional second argument for most generated API request methods (e.g., client.merchant.get(params?: FetchParams)). It allows developers to customize the underlying fetch call for specific requests. For example, you can use FetchParams to:

• Add custom HTTP headers.
• Pass a signal for request cancellation.
• Configure credentials for cross-origin requests.

This provides fine-grained control over individual API requests without altering the core SDK configuration.

FullParams for Internal Request Parameters

FullParams is an internal type definition used by the SDK's core HTTPClient for making requests. It extends FetchParams with additional properties essential for constructing a complete API request:

• path: The API endpoint path.
• query: An object representing query parameters to be appended to the URL.
• body: The request body data.
• host: An optional host override, allowing a request to target a different API host than the one configured for the client.
• method: The HTTP method (e.g., GET, POST, PUT).

FullParams serves as a comprehensive internal contract for the HTTPClient's request method, ensuring all necessary information is present to dispatch an HTTP call correctly. While developers primarily interact with FetchParams, FullParams is crucial for the SDK's internal request processing logic.