shipy-sdk-js/README.md

Shipy Payment Gateway SDK for JavaScript/TypeScript

# Shipy SDK for JavaScript/TypeScript

A modern, type-safe SDK for integrating with the Shipy Payment Gateway. Built with TypeScript, works with both JavaScript and TypeScript projects.

## Features

- 🚀 **TypeScript First**: Full TypeScript support with type definitions
- 💳 **Multiple Payment Methods**: Support for credit card and mobile payments
- 🔒 **Secure**: Built-in callback verification
- 🎯 **Zero Dependencies**: Uses native `fetch` API
- 📦 **Tree-shakeable**: Only import what you need
- ✅ **100% Test Coverage**: Fully tested with Jest

## Installation

```bash
npm install shipy-sdk-js
# or
yarn add shipy-sdk-js
# or
pnpm add shipy-sdk-js
```

## Quick Start

```typescript
import { Shipy } from 'shipy-sdk-js';

// Initialize with your API key
const shipy = new Shipy('your-api-key');

// Create a credit card payment
const payment = await shipy.creditCard.pay({
  returnID: 'order123',
  usrIp: '127.0.0.1',
  amount: 100,
  usrName: 'John Doe',
  usrAddress: '123 Main St',
  usrPhone: '5551234567',
  usrEmail: 'john@example.com',
  currency: 'TRY',
  pageLang: 'TR',
  mailLang: 'TR',
  installment: 0
});

// Redirect user to payment page
window.location.href = payment.link;
```

## API Reference

### Credit Card Payments

```typescript
const payment = await shipy.creditCard.pay({
  // Required fields
  returnID: string | number,
  usrIp: string,
  usrName: string,
  usrAddress: string,
  usrPhone: string,
  usrEmail: string,
  amount: number,

  // Optional fields
  currency?: 'TRY' | 'USD' | 'EUR' | 'GBP',
  pageLang?: 'TR' | 'EN' | 'DE' | 'AR' | 'ES' | 'FR',
  mailLang?: 'TR' | 'EN',
  installment?: 0 | 3 | 6 | 9 | 12
});
```

### Mobile Payments

```typescript
const payment = await shipy.mobile.pay({
  // Required fields
  returnID: string | number,
  usrIp: string,
  usrName: string,
  usrAddress: string,
  usrPhone: string,
  usrEmail: string,
  amount: number
});
```

### Event Handling

```typescript
// Listen for payment success
shipy.creditCard.eventEmitter.on('payment.success', (data) => {
  console.log('Payment successful:', data);
});

// Listen for payment pending
shipy.creditCard.eventEmitter.on('payment.pending', (data) => {
  console.log('Payment pending:', data);
});

// Listen for errors
shipy.creditCard.eventEmitter.on('error', (error) => {
  console.error('Payment error:', error);
});
```

### Callback Verification

```typescript
// Verify callback data
const isValid = shipy.creditCard.verifyCallback({
  paymentID: string,
  returnID: string,
  paymentType: 'credit_card' | 'mobile' | 'eft',
  paymentAmount: number,
  paymentCurrency: string,
  paymentHash: string
});
```

## Error Handling

```typescript
try {
  const payment = await shipy.creditCard.pay({
    // ... payment details
  });
  
  if (payment.status === 'success') {
    window.location.href = payment.link;
  }
} catch (error) {
  console.error('Payment failed:', error.message);
}
```

## Development

```bash
# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Build
pnpm build
```

## 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.