@tapsilat/tapsilat-js 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,541 @@
+interface TapsilatConfig {
+    bearerToken: string;
+    baseURL?: string;
+    timeout?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+    version?: string;
+    debug?: boolean;
+}
+interface APIResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        message: string;
+        code: string;
+        details?: any;
+    };
+    status?: number;
+    headers?: Record<string, string>;
+}
+interface APIError {
+    message: string;
+    code: string;
+    details?: Record<string, any>;
+}
+type Currency = "TRY" | "USD" | "EUR" | "GBP";
+type PaymentMethod = "credit_card" | "debit_card" | "bank_transfer" | "digital_wallet";
+type PaymentStatus = "pending" | "completed" | "failed" | "cancelled" | "refunded";
+interface PaymentRequest {
+    amount: number;
+    currency: Currency;
+    paymentMethod: PaymentMethod;
+    description?: string;
+    returnUrl?: string;
+    cancelUrl?: string;
+    webhookUrl?: string;
+    metadata?: Record<string, any>;
+    customerId?: string;
+}
+interface PaymentResponse {
+    id: string;
+    amount: number;
+    currency: Currency;
+    paymentMethod: PaymentMethod;
+    status: PaymentStatus;
+    description?: string;
+    returnUrl?: string;
+    cancelUrl?: string;
+    webhookUrl?: string;
+    metadata?: Record<string, any>;
+    customerId?: string;
+    paymentUrl?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RefundRequest {
+    paymentId: string;
+    amount?: number;
+    reason?: string;
+    metadata?: Record<string, any>;
+}
+interface RefundResponse {
+    id: string;
+    paymentId: string;
+    amount: number;
+    currency: Currency;
+    status: "pending" | "completed" | "failed";
+    reason?: string;
+    metadata?: Record<string, any>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Customer {
+    id?: string;
+    email: string;
+    name: string;
+    phone?: string;
+    address?: Address;
+    metadata?: Record<string, any>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface Address {
+    street: string;
+    city: string;
+    country: string;
+    postalCode: string;
+}
+interface PaginationParams {
+    page?: number;
+    limit?: number;
+    sortBy?: string;
+    sortOrder?: "asc" | "desc";
+}
+interface PaginatedResponse<T> {
+    page: number;
+    per_page: number;
+    rows: T[];
+    total: number;
+    total_pages: number;
+}
+interface WebhookEvent {
+    id: string;
+    type: "payment.completed" | "payment.failed" | "payment.cancelled" | "refund.completed" | "refund.failed";
+    data: PaymentResponse | RefundResponse;
+    createdAt: string;
+    signature: string;
+}
+/**
+ * Represents the buyer information.
+ * Based on BuyerDTO from the Python SDK.
+ */
+interface Buyer$1 {
+    name: string;
+    surname: string;
+    email: string;
+}
+/**
+ * Represents the response received after creating an order.
+ */
+interface OrderCreateResponse$1 {
+    referenceId: string;
+    conversationId: string;
+    checkoutUrl: string;
+    status: string;
+    qrCodeUrl?: string;
+}
+/**
+ * Represents a full order object with all details.
+ */
+interface Order extends OrderCreateResponse$1 {
+    amount: number | string;
+    currency: Currency;
+    buyer?: Buyer$1;
+    description?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: Record<string, unknown>;
+    id?: string;
+    name?: string;
+    email?: string;
+    total?: string;
+    checkout_url?: string;
+    organization?: string;
+    unpaid_amount?: number;
+}
+/**
+ * Represents the data needed to request a refund for an order.
+ */
+interface OrderRefundRequest {
+    reference_id: string;
+    amount: number;
+}
+/**
+ * Represents the response received after a refund request.
+ */
+interface OrderRefundResponse {
+    refundId: string;
+    referenceId: string;
+    status: string;
+    amount: number;
+    currency: Currency;
+    createdAt: string;
+}
+/**
+ * Represents the status of an order.
+ */
+interface OrderStatusResponse {
+    referenceId: string;
+    status: string;
+    lastUpdatedAt: string;
+}
+/**
+ * Represents the details of a payment transaction associated with an order.
+ */
+interface OrderPaymentDetail {
+    transactionId: string;
+    paymentMethod: string;
+    amount: number;
+    currency: Currency;
+    status: string;
+    paidAt: string;
+    cardInfo?: {
+        binNumber: string;
+        lastFourDigits: string;
+        cardAssociation: string;
+    };
+}
+
+/**
+ * Supported locales for the Tapsilat API.
+ */
+type Locale = "tr" | "en";
+/**
+ * Represents the buyer information.
+ * Based on BuyerDTO from the Python SDK.
+ */
+interface Buyer {
+    name: string;
+    surname: string;
+    email: string;
+    phone?: string;
+    identityNumber?: string;
+    shippingAddress?: Address;
+    billingAddress?: Address;
+}
+/**
+ * Represents the data required to create a new order.
+ * Based on OrderCreateDTO from the Python SDK.
+ */
+interface OrderCreateRequest {
+    amount: number;
+    currency: Currency;
+    locale: Locale;
+    buyer: Buyer;
+    description?: string;
+    callbackUrl?: string;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Represents the response received after creating an order.
+ */
+interface OrderCreateResponse {
+    referenceId: string;
+    conversationId: string;
+    checkoutUrl: string;
+    status: string;
+    qrCodeUrl?: string;
+}
+/**
+ * Main SDK class for Tapsilat payment operations
+ *
+ * @example
+ * ```typescript
+ * const tapsilat = new TapsilatSDK({
+ *   bearerToken: 'your-bearer-token',
+ *   baseURL: 'https://api.tapsilat.com/v1'
+ * });
+ *
+ * const payment = await tapsilat.createPayment({
+ *   amount: 100.50,
+ *   currency: 'TRY',
+ *   paymentMethod: 'credit_card'
+ * });
+ * ```
+ */
+declare class TapsilatSDK {
+    private readonly httpClient;
+    private readonly config;
+    /**
+     * Creates a new TapsilatSDK instance
+     *
+     * @param config - SDK configuration options
+     * @throws {TapsilatValidationError} When Bearer token is invalid
+     */
+    constructor(config: TapsilatConfig);
+    /**
+     * Creates a new order and returns a checkout URL.
+     *
+     * @param orderRequest - The order details including amount, currency, and buyer information
+     * @returns Promise resolving to the created order response including reference ID and checkout URL
+     * @throws {TapsilatValidationError} When order request data is invalid
+     * @throws {TapsilatNetworkError} When API request fails due to network issues
+     * @throws {TapsilatError} When API returns an error response
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const orderResponse = await tapsilat.createOrder({
+     *     amount: 100.50,
+     *     currency: 'TRY',
+     *     locale: 'en',
+     *     buyer: {
+     *       name: 'John',
+     *       surname: 'Doe',
+     *       email: 'john.doe@example.com'
+     *     }
+     *   });
+     *   console.log(`Checkout URL: ${orderResponse.checkoutUrl}`);
+     * } catch (error) {
+     *   console.error(`Order creation failed: ${error.message}`);
+     * }
+     * ```
+     */
+    createOrder(orderRequest: OrderCreateRequest): Promise<OrderCreateResponse>;
+    /**
+     * Validates an order request object
+     * @private
+     */
+    private validateOrderRequest;
+    /**
+     * Basic email validation
+     * @private
+     */
+    private isValidEmail;
+    /**
+     * Generic response handler - consistent way to handle API responses across SDK methods
+     * @private
+     *
+     * @param response - The API response to process
+     * @param errorContext - Descriptive context for error messages
+     * @returns The data from a successful response
+     * @throws {TapsilatError} On any response error
+     */
+    private handleResponse;
+    /**
+     * Generic error handler - consistent way to handle errors across SDK methods
+     * @private
+     *
+     * @param error - The caught error to process
+     * @param errorContext - Descriptive context for error messages
+     * @throws {TapsilatError} Always throws an appropriate error type
+     */
+    private handleError;
+    /**
+     * Gets an order by reference ID.
+     *
+     * @param referenceId - The unique reference ID of the order
+     * @returns Promise resolving to the complete order details
+     * @throws {TapsilatValidationError} When referenceId is invalid
+     * @throws {TapsilatNetworkError} When API request fails due to network issues
+     * @throws {TapsilatError} When API returns an error response
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const order = await tapsilat.getOrder("ord_123456789");
+     *   console.log(`Order amount: ${order.amount} ${order.currency}`);
+     * } catch (error) {
+     *   console.error(`Failed to get order: ${error.message}`);
+     * }
+     * ```
+     */
+    getOrder(referenceId: string): Promise<Order>;
+    /**
+     * Lists orders with pagination support.
+     *
+     * @param params - Optional pagination parameters (page number and items per page)
+     * @returns Promise resolving to paginated list of orders
+     * @throws {TapsilatNetworkError} When API request fails due to network issues
+     * @throws {TapsilatError} When API returns an error response
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Get the second page with 20 items per page
+     *   const orderList = await tapsilat.getOrders({ page: 2, per_page: 20 });
+     *   console.log(`Total orders: ${orderList.total}`);
+     *   orderList.rows.forEach(order => {
+     *     console.log(`Order ${order.referenceId}: ${order.amount} ${order.currency}`);
+     *   });
+     * } catch (error) {
+     *   console.error(`Failed to list orders: ${error.message}`);
+     * }
+     * ```
+     */
+    getOrders(params?: {
+        page?: number;
+        per_page?: number;
+    }): Promise<PaginatedResponse<Order>>;
+    /**
+     * Cancels an order by reference_id.
+     */
+    cancelOrder(referenceId: string): Promise<Order>;
+    /**
+     * Gets the status of an order by reference ID.
+     *
+     * @param referenceId - The unique reference ID of the order
+     * @returns Promise resolving to the current order status, including status code and last update time
+     * @throws {TapsilatValidationError} When referenceId is invalid
+     * @throws {TapsilatNetworkError} When API request fails due to network issues
+     * @throws {TapsilatError} When API returns an error response
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const orderStatus = await tapsilat.getOrderStatus("ord_123456789");
+     *   console.log(`Order status: ${orderStatus.status}`);
+     * } catch (error) {
+     *   if (error instanceof TapsilatValidationError) {
+     *     console.error("Invalid reference ID format");
+     *   } else if (error instanceof TapsilatError) {
+     *     console.error(`API error: ${error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    getOrderStatus(referenceId: string): Promise<OrderStatusResponse>;
+    /**
+     * Partially refunds an order.
+     * Based on `refund_order` from the Python SDK.
+     *
+     * @param refundData - The refund details, including referenceId and amount.
+     * @returns Promise resolving to the refund transaction details.
+     */
+    refundOrder(refundData: OrderRefundRequest): Promise<OrderRefundResponse>;
+    /**
+     * Fully refunds an order by its reference ID.
+     * Based on `refund_all_order` from the Python SDK.
+     *
+     * @param referenceId - The unique identifier of the order to fully refund.
+     * @returns Promise resolving to the refund transaction details.
+     */
+    refundAllOrder(referenceId: string): Promise<OrderRefundResponse>;
+    /**
+     * Retrieves the payment details for an order.
+     * Based on `get_order_payment_details` from the Python SDK.
+     *
+     * @param referenceId - The unique identifier of the order.
+     * @param conversationId - Optional conversation ID for more specific querying.
+     * @returns Promise resolving to a list of payment details.
+     */
+    getOrderPaymentDetails(referenceId: string, conversationId?: string): Promise<OrderPaymentDetail[]>;
+    /**
+     * Gets an order by conversation_id.
+     * Based on `get_order_by_conversation_id` from the Python SDK.
+     */
+    getOrderByConversationId(conversationId: string): Promise<Order>;
+    /**
+     * Gets order transactions by reference_id.
+     * Based on `get_order_transactions` from the Python SDK.
+     */
+    getOrderTransactions(referenceId: string): Promise<any[]>;
+    /**
+     * Gets order submerchants with pagination.
+     * Based on `get_order_submerchants` from the Python SDK.
+     */
+    getOrderSubmerchants(params?: {
+        page?: number;
+        per_page?: number;
+    }): Promise<any>;
+    /**
+     * Gets checkout URL for an order.
+     * Based on `get_checkout_url` from the Python SDK.
+     */
+    getCheckoutUrl(referenceId: string): Promise<string>;
+    /**
+     * Verifies webhook signature for security
+     *
+     * @param payload - Raw webhook payload string
+     * @param signature - Webhook signature from headers
+     * @param secret - Your webhook secret key
+     * @returns Promise resolving to true if signature is valid
+     *
+     * @example
+     * ```typescript
+     * const isValid = await sdk.verifyWebhook(
+     *   JSON.stringify(req.body),
+     *   req.headers['x-tapsilat-signature'],
+     *   'your-webhook-secret'
+     * );
+     * ```
+     */
+    verifyWebhook(payload: string, signature: string, secret: string): Promise<boolean>;
+    /**
+     * Checks API service health and availability
+     *
+     * @returns Promise resolving to service status
+     */
+    healthCheck(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+    /**
+     * Gets current SDK configuration (without sensitive data)
+     *
+     * @returns Copy of current configuration
+     */
+    getConfig(): Omit<TapsilatConfig, "bearerToken"> & {
+        hasBearerToken: boolean;
+    };
+    /**
+     * Updates SDK configuration
+     *
+     * @param newConfig - Partial configuration to update
+     * @throws {TapsilatValidationError} When Bearer token is invalid
+     */
+    updateConfig(newConfig: Partial<TapsilatConfig>): void;
+}
+
+declare class TapsilatError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, any>;
+    constructor(message: string, code: string, details?: Record<string, any>);
+    static fromAPIError(apiError: APIError): TapsilatError;
+}
+declare class TapsilatNetworkError extends TapsilatError {
+    readonly statusCode?: number;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, any>);
+}
+declare class TapsilatValidationError extends TapsilatError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class TapsilatAuthenticationError extends TapsilatError {
+    constructor(message?: string);
+}
+declare class TapsilatRateLimitError extends TapsilatError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+
+/**
+ * Validates payment request data comprehensively
+ *
+ * @param request - Payment request to validate
+ * @throws {TapsilatValidationError} When any field is invalid
+ */
+declare function validatePaymentRequest(request: unknown): asserts request is PaymentRequest;
+/**
+ * Validates email format using robust regex
+ *
+ * @param email - Email address to validate
+ * @returns True if email format is valid
+ */
+declare function validateEmail(email: string): boolean;
+/**
+ * @deprecated Use isCurrency type guard instead
+ */
+declare function isValidCurrency(currency: string): boolean;
+/**
+ * @deprecated Use isPaymentMethod type guard instead
+ */
+declare function isValidPaymentMethod(paymentMethod: string): boolean;
+/**
+ * Validates URL format and protocol
+ *
+ * @param url - URL to validate
+ * @returns True if URL is valid HTTP/HTTPS
+ */
+declare function isValidUrl(url: string): boolean;
+/**
+ * Sanitizes metadata by removing sensitive keys and cleaning values
+ *
+ * @param metadata - Raw metadata object
+ * @returns Sanitized metadata object
+ */
+declare function sanitizeMetadata(metadata: Record<string, unknown>): Record<string, unknown>;
+
+export { TapsilatAuthenticationError, TapsilatError, TapsilatNetworkError, TapsilatRateLimitError, TapsilatSDK, TapsilatValidationError, isValidCurrency, isValidPaymentMethod, isValidUrl, sanitizeMetadata, validateEmail, validatePaymentRequest };
+export type { APIError, APIResponse, Address, Currency, Customer, PaginatedResponse, PaginationParams, PaymentMethod, PaymentRequest, PaymentResponse, PaymentStatus, RefundRequest, RefundResponse, TapsilatConfig, WebhookEvent };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,YAAY,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,QAAQ,EACR,cAAc,EACd,eAAe,EACf,QAAQ,EACR,OAAO,EACP,aAAa,EACb,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,gBAAgB,GACjB,MAAM,oBAAoB,CAAC"}