@letsparky/api-v2-client/dist/payments.d.ts

TypeScript client for the LetsParky API V2

import { ApiClient } from './client';
import { Payment, PaymentFilters, PaymentListResponse, ApiResponse, PaginationParams, PaginatedResponse, UUID } from './types';
/**
 * 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
 */
export declare class Payments {
    private client;
    constructor(client: ApiClient);
    /**
     * 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
     */
    list(filters?: PaymentFilters): Promise<ApiResponse<PaymentListResponse>>;
    /**
     * 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
     */
    listPaginated(paginationParams: PaginationParams, filters?: PaymentFilters): Promise<PaginatedResponse<Payment>>;
    /**
     * 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
     */
    get(paymentId: number): Promise<ApiResponse<Payment>>;
    /**
     * 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
     */
    getByUserId(user_id: UUID, paginationParams?: PaginationParams): Promise<ApiResponse<PaymentListResponse>>;
}