npm package: @longswipe/longswipe-node
Description: Longswipe Node.js SDK for merchant integrations
Author: Longswipe
Latest version: 1.0.8

# @longswipe/longswipe-node

Official Node.js SDK for Longswipe merchant integrations.

[![npm version](https://badge.fury.io/js/@longswipe%2Flongswipe-node.svg)](https://badge.fury.io/js/@longswipe%2Flongswipe-node)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
npm install @longswipe/longswipe-node
```

Or with yarn:

```bash
yarn add @longswipe/longswipe-node
```

## Usage

```typescript
import { LongswipeSDK } from '@longswipe/longswipe-node';

// Initialize the SDK
const longswipe = new LongswipeSDK({
  environment:'production' // 'sandbox' for test environment
  publicKey: 'your_public_key',
  secretKey: 'your_secret_key'  // Only required for authenticated endpoints
});
```

## API Reference

### Configuration

The SDK constructor accepts a configuration object with the following properties:


```typescript
interface LongswipeConfig {
  publicKey: string; // required for all endpoints
  secretKey?: string; // required for authenticated endpoints
  environment: 'sandbox' | 'production'; // required
}
```

### Authenticated Endpoints

These endpoints require both public and secret keys.


#### Customer Management

1. Add New Customer
```typescript
addNewCustomer(customer: { email: string; name: string }): Promise<ApiResponse>
```

2. Update Customer
```typescript
updateCustomer(customer: { id: string; email: string; name: string }): Promise<ApiResponse>
```

3. Delete Customer
```typescript
deleteCustomer(customerID: string): Promise<ApiResponse>
```

4. Fetch Customer by Email
```typescript
fetchCustomerByEmail(email: string): Promise<CustomerResponse>
```

5. Fetch Customers (with pagination)
```typescript
fetchCustomers(params?: { page?: number; limit?: number; search?: string }): Promise<CustomersResponse>
```

#### Invoice Management

1. Create Invoice
```typescript
createInvoice(invoice: {
  blockchainNetworkAbbreviation?: string;
  currencyAbbreviation: string;
  dueDate: string;
  invoiceDate: string;
  invoiceItems: Array<{
    description: string;
    quantity: number;
    unitPrice: number;
  }>;
  merchantCode: string;
  email: string;
  fullName: string;
}): Promise<ApiResponse>
```

2. Approve Invoice
```typescript
approveInvoice({ invoiceID, onChain }: { invoiceID: string; onChain: boolean }): Promise<ApiResponse>
```

3. Get Invoices
```typescript
getInvoices({ page, limit, filter }: { page?: number; limit?: number; filter?: 'Approved' | 'Pending' | 'Rejected' }): Promise<Invoices>
```

#### Service Health & Transaction

1. Health Check
```typescript
healthCheck(): Promise<ApiResponse>
```

2. Verify Transaction
```typescript
verifyTransaction(referenceID: string): Promise<VerifyTransactionResponse>
```


### Public Endpoints

These endpoints only require the public key.

#### Crypto Networks and Currencies

1. Fetch Supported Crypto Networks
```typescript
fetchSupportedCryptoNetworks(): Promise<CryptoNetworksResponse>
```

2. Fetch Supported Currencies
```typescript
fetchSupportedCurrencies(): Promise<CurrenciesResponse>
```

#### Voucher Operations

1. Fetch Voucher Redemption Charges
```typescript
fetchVoucherRedemptionCharges(request: VoucherRedemptionRequest): Promise<VoucherRedemptionChargesResponse>
```

2. Redeem Voucher
```typescript
redeemVoucher(request: VoucherRedemptionRequest): Promise<ApiResponse>
```

3. Verify Voucher
```typescript
verifyVoucher(request: { voucherCode: string }): Promise<VerifyVoucherResponse>
```

#### Payment & Deposit Operations

1. Payment Request
```typescript
paymentRequest(request: {
  amount: number;
  currency: string;
  user_identifier: string;
  metadata: { [key: string]: string | number | boolean };
  reference_id: string;
}): Promise<ApiResponse>
```

2. Verify User Payment
```typescript
verifyUserPayment({ user: string }): Promise<VerifyUserPaymentResponse>
```

3. Deposit Address Request
```typescript
depositAddressRequest(request: {
  amount: number;
  currency_abbreviation: string;
  blockchainNetworkId: string;
  metadata: { [key: string]: string | number | boolean };
  pay_with_currency_abbreviation: string;
  reference_id: string;
}): Promise<DepositAddressPaymentResponse>
```

4. Deposit Address Charges Request
```typescript
depositAddressChargesRequest(request: {
  amount: number;
  blockchainNetworkId: string;
  currency_abbreviation: string;
  pay_with_currency_abbreviation: string;
}): Promise<DepositAddressPaymentChargesResponse>
```

5. Get Application Details
```typescript
getApplication(): Promise<ApplicationResponse>
```


### Response Types

All API responses follow this structure:

```typescript
interface ApiResponse<T = any> {
  code: number;
  message: string;
  status: string;
  data?: T;
}
```

Specific responses include additional data:

```typescript
interface Customer {
  id?: string;
  email: string;
  name: string;
  merchantID?: string;
}

interface CustomerResponse extends ApiResponse {
  customer?: Customer;
}

interface CustomersResponse extends ApiResponse {
  data?: {
    customer: Customer[];
    page: number;
    limit: number;
    total: number;
  };
}

interface InvoiceItem {
  description: string;
  quantity: number;
  unitPrice: number;
}

interface Invoice {
  blockchainNetworkAbbreviation?: string;
  currencyAbbreviation: string;
  dueDate: string;
  invoiceDate: string;
  invoiceItems: InvoiceItem[];
  merchantCode: string;
  email: string;
  fullName: string;
}

interface Invoices extends ApiResponse {
  data?: {
    invoices: Array<{ /* ...invoice fields... */ }>;
    total: number;
  };
}

// Crypto network response
interface CryptoNetworksResponse extends ApiResponse {
  data?: Array<{
    blockExplorerUrl: string;
    chainID: string;
    cryptocurrencies: Array<{
      currencyAddress: string;
      currencyData: {
        abbrev: string;
        currencyType: string;
        id: string;
        image: string;
        isActive: boolean;
        name: string;
        symbol: string;
      };
      currencyDecimals: string;
      currencyName: string;
      id: string;
      longswipeContractAddress: string;
      networkID: string;
      status: boolean;
    }>;
    id: string;
    networkName: string;
    networkType: string;
    rpcUrl: string;
  }>;
}

// Currencies response
interface CurrenciesResponse extends ApiResponse {
  data?: {
    currencies: Array<{
      abbreviation: string;
      createdAt: string;
      currency: string;
      currencyType: string;
      id: string;
      image: string;
      isActive: boolean;
      symbol: string;
    }>;
  };
}
```

## Error Handling

The SDK throws errors for:
- Network issues
- Invalid API keys
- Missing required fields
- Server errors

Example error handling:

```typescript
try {
  await longswipe.addNewCustomer({
    email: 'customer@example.com',
    name: 'John Doe'
  });
} catch (error) {
  if (error.response) {
    // The request was made and the server responded with a status code
    // that falls out of the range of 2xx
    console.error('Error response:', error.response.data);
  } else if (error.request) {
    // The request was made but no response was received
    console.error('No response received:', error.request);
  } else {
    // Something happened in setting up the request that triggered an Error
    console.error('Error:', error.message);
  }
}
```

## Development

1. Clone the repository
```bash
git clone https://github.com/longswipe/longswipe-node.git
cd longswipe-node
```

2. Install dependencies
```bash
npm install
```

3. Build the package
```bash
npm run build
```

4. Run in development mode with watch
```bash
npm run dev
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

For support, email support@longswipe.com or visit https://longswipe.com/support

## Links

- [GitHub Repository](https://github.com/longswipe/longswipe-node)
- [Issue Tracker](https://github.com/longswipe/longswipe-node/issues)
- [Documentation](https://github.com/longswipe/longswipe-node#readme)