@imerchantsolutions/sdk 1.0.0

package/README.md

@@ -0,0 +1,204 @@
+# @imerchantsolutions/sdk
+
+Official JavaScript/TypeScript SDK for the iMerchant Payments API.
+
+## Installation
+
+```bash
+npm install @imerchantsolutions/sdk
+# or
+yarn add @imerchantsolutions/sdk
+# or
+pnpm add @imerchantsolutions/sdk
+```
+
+## Quick Start
+
+```typescript
+import { iMerchant } from '@imerchantsolutions/sdk';
+
+const client = new iMerchant({
+  apiKey: 'sk_test_your_api_key'
+});
+
+// Create a payment
+const payment = await client.payments.create({
+  amount: 1000,        // $10.00 in cents
+  currency: 'usd',
+  reference: 'order_123',
+  description: 'Test payment'
+});
+
+console.log('Payment ID:', payment.id);
+```
+
+## Features
+
+- **Full TypeScript support** with comprehensive type definitions
+- **Payments** - Create, capture, cancel, and list payments
+- **Refunds** - Process full or partial refunds
+- **Customers** - Manage customer profiles
+- **Subscriptions** - Handle recurring billing
+- **Webhooks** - Verify webhook signatures securely
+
+## API Reference
+
+### Payments
+
+```typescript
+// Create a payment
+const payment = await client.payments.create({
+  amount: 2000,
+  currency: 'usd',
+  reference: 'order_456',
+  customerId: 'cus_abc123',
+  returnUrl: 'https://yoursite.com/complete'
+});
+
+// Retrieve a payment
+const payment = await client.payments.retrieve('pay_abc123');
+
+// List payments
+const { data, hasMore } = await client.payments.list({
+  status: 'captured',
+  limit: 10
+});
+
+// Capture an authorized payment
+await client.payments.capture('pay_abc123');
+
+// Cancel a payment
+await client.payments.cancel('pay_abc123');
+```
+
+### Refunds
+
+```typescript
+// Create a full refund
+const refund = await client.refunds.create({
+  paymentId: 'pay_abc123',
+  reason: 'Customer request'
+});
+
+// Create a partial refund
+const refund = await client.refunds.create({
+  paymentId: 'pay_abc123',
+  amount: 500,  // $5.00 in cents
+  reason: 'Partial return'
+});
+
+// List refunds
+const { data } = await client.refunds.list({
+  paymentId: 'pay_abc123'
+});
+```
+
+### Customers
+
+```typescript
+// Create a customer
+const customer = await client.customers.create({
+  email: 'john@example.com',
+  firstName: 'John',
+  lastName: 'Doe'
+});
+
+// Update a customer
+const customer = await client.customers.update('cus_abc123', {
+  phone: '+1234567890'
+});
+
+// List customers
+const { data } = await client.customers.list({ limit: 20 });
+```
+
+### Subscriptions
+
+```typescript
+// Create a subscription
+const subscription = await client.subscriptions.create({
+  customerId: 'cus_abc123',
+  amount: 2999,
+  currency: 'usd',
+  interval: 'month',
+  trialDays: 14
+});
+
+// Cancel a subscription
+await client.subscriptions.cancel('sub_abc123', {
+  atPeriodEnd: true
+});
+
+// Pause/Resume
+await client.subscriptions.pause('sub_abc123');
+await client.subscriptions.resume('sub_abc123');
+```
+
+### Webhooks
+
+```typescript
+import { iMerchant } from '@imerchantsolutions/sdk';
+
+// Express.js example
+app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['imerchant-signature'];
+
+  try {
+    const event = iMerchant.webhooks.verify(
+      { body: req.body.toString(), signature },
+      process.env.WEBHOOK_SECRET
+    );
+
+    switch (event.type) {
+      case 'payment.captured':
+        // Handle successful payment
+        break;
+      case 'payment.failed':
+        // Handle failed payment
+        break;
+    }
+
+    res.json({ received: true });
+  } catch (err) {
+    res.status(400).send('Invalid signature');
+  }
+});
+```
+
+## Error Handling
+
+```typescript
+import {
+  iMerchant,
+  APIError,
+  AuthenticationError,
+  ValidationError
+} from '@imerchantsolutions/sdk';
+
+try {
+  await client.payments.create({ ... });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof ValidationError) {
+    console.error('Validation errors:', error.errors);
+  } else if (error instanceof APIError) {
+    console.error(`API Error: ${error.code} - ${error.message}`);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const client = new iMerchant({
+  apiKey: 'sk_test_...',      // Required
+  baseUrl: 'https://...',     // Optional: custom API URL
+  timeout: 30000,             // Optional: request timeout in ms
+  apiVersion: 'v1'            // Optional: API version
+});
+```
+
+## License
+
+MIT