@letsparky/api-v2-client
Version:
TypeScript client for the LetsParky API V2
182 lines (181 loc) • 6.51 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.Payments = void 0;
const validators_1 = require("./validators");
/**
* Payments API client for managing payment operations.
*
* This class provides methods for interacting with payment-related endpoints
* in the LetsParky API, including listing payments, retrieving payment details,
* and filtering payments by various criteria.
*
* @example
* ```typescript
* const client = new LetsParkyClient({ apiKey: 'your-api-key' });
*
* // List all payments
* const payments = await client.payments.list();
*
* // Get payments for a specific user
* const userPayments = await client.payments.getByUserId('user-id');
*
* // Filter payments by status and amount
* const filteredPayments = await client.payments.list({
* status: PaymentStatus.CAPTURED,
* min_amount: 10.00,
* currency: 'USD'
* });
* ```
*
* @since 1.0.0
*/
class Payments {
constructor(client) {
this.client = client;
}
/**
* Get a paginated list of payments with optional filtering.
*
* This method retrieves payments with support for various filtering options
* including user ID, payment type, status, amount ranges, and more.
*
* @param filters - Optional filter parameters for payments
* @returns Promise resolving to a paginated list of payments
*
* @throws {AuthenticationError} When authentication is required or fails
* @throws {ApiError} When the API returns an error response
* @throws {NetworkError} When the request fails due to network issues
* @throws {ValidationError} When filter parameters are invalid
*
* @example
* ```typescript
* // Get all payments
* const allPayments = await client.payments.list();
*
* // Filter by payment status
* const capturedPayments = await client.payments.list({
* status: PaymentStatus.CAPTURED,
* page: 1,
* limit: 50
* });
*
* // Filter by amount range and currency
* const expensivePayments = await client.payments.list({
* min_amount: 100,
* currency: 'USD',
* sort_by: 'amount',
* sort_direction: 'desc'
* });
* ```
*
* @since 1.0.0
*/
async list(filters) {
return this.client.get('/payments', filters);
}
/**
* Get a paginated list of payments with pagination controls.
*
* This method provides explicit pagination control while maintaining
* the ability to apply filters.
*
* @param paginationParams - Pagination parameters (page, limit, sort, order)
* @param filters - Optional filter parameters for payments
* @returns Promise resolving to a paginated response with payments
*
* @throws {AuthenticationError} When authentication is required or fails
* @throws {ApiError} When the API returns an error response
* @throws {NetworkError} When the request fails due to network issues
* @throws {ValidationError} When pagination or filter parameters are invalid
*
* @example
* ```typescript
* // Get second page of payments with 25 items per page
* const pagedPayments = await client.payments.listPaginated(
* { page: 2, limit: 25, sort: 'created_at', order: 'desc' },
* { status: PaymentStatus.CAPTURED }
* );
*
* console.log(`Page ${pagedPayments.page} of ${pagedPayments.pages}`);
* console.log(`${pagedPayments.data.length} payments returned`);
* ```
*
* @since 1.0.0
*/
async listPaginated(paginationParams, filters) {
return this.client.getPaginated('/payments', paginationParams, filters);
}
/**
* Get a specific payment by ID.
*
* This method retrieves detailed information about a specific payment,
* including all transaction details, status, and metadata.
*
* @param paymentId - The ID of the payment to retrieve
* @returns Promise resolving to the payment details
*
* @throws {AuthenticationError} When authentication is required or fails
* @throws {ApiError} When the API returns an error response (e.g., 404 if payment not found)
* @throws {NetworkError} When the request fails due to network issues
* @throws {ValidationError} When the payment ID is invalid
*
* @example
* ```typescript
* try {
* const payment = await client.payments.get(123);
* console.log(`Payment ${payment.data.id}: ${payment.data.status}`);
* console.log(`Amount: ${payment.data.amount} ${payment.data.currency}`);
* } catch (error) {
* if (error.status === 404) {
* console.log('Payment not found');
* }
* }
* ```
*
* @since 1.0.0
*/
async get(paymentId) {
validators_1.Validators.validateId(paymentId.toString(), 'Payment');
return this.client.get(`/payments/${paymentId}`);
}
/**
* Get payments for a specific user.
*
* This method retrieves all payments associated with a specific user,
* with support for pagination.
*
* @param user_id - The UUID of the user whose payments to retrieve
* @param paginationParams - Optional pagination parameters
* @returns Promise resolving to a paginated list of user payments
*
* @throws {AuthenticationError} When authentication is required or fails
* @throws {ApiError} When the API returns an error response (e.g., 404 if user not found)
* @throws {NetworkError} When the request fails due to network issues
* @throws {ValidationError} When the user ID is invalid
*
* @example
* ```typescript
* // Get all payments for a user
* const userPayments = await client.payments.getByUserId('user-uuid');
*
* // Get first page of user payments with pagination
* const pagedUserPayments = await client.payments.getByUserId(
* 'user-uuid',
* { page: 1, limit: 10 }
* );
*
* console.log(`User has ${userPayments.data.length} payments`);
* ```
*
* @since 1.0.0
*/
async getByUserId(user_id, paginationParams) {
validators_1.Validators.validateId(user_id, 'User ID');
const params = paginationParams ? {
page: paginationParams.page,
limit: paginationParams.limit
} : undefined;
return this.client.get(`/payments/user/${user_id}`, params);
}
}
exports.Payments = Payments;