@delopay/sdk 0.1.0

package/README.md

@@ -0,0 +1,254 @@
+# @delopay/sdk
+
+TypeScript SDK for the [Delopay](https://delopay.net) payments API. Zero dependencies, works in Node 18+ and browsers.
+
+## Installation
+
+```bash
+pnpm add @delopay/sdk
+```
+
+```bash
+npm install @delopay/sdk
+```
+
+```bash
+yarn add @delopay/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Delopay } from '@delopay/sdk';
+
+const delopay = new Delopay(process.env.DELOPAY_API_KEY!);
+
+const payment = await delopay.payments.create({
+  amount: 1000, // in minor units (€10.00)
+  currency: 'EUR',
+  description: 'Order #1234',
+  customer_id: 'cus_abc123',
+});
+
+console.log(payment.payment_id, payment.status);
+```
+
+## Configuration
+
+```typescript
+const delopay = new Delopay(apiKey, {
+  sandbox: true, // Use https://sandbox.delopay.net (default: false → production)
+  baseUrl: 'https://…', // Override base URL entirely
+  timeout: 30_000, // Request timeout in ms (default: 30 000)
+});
+```
+
+**API keys:**
+
+- `sk_*` — server-side secret key. Full API access. Keep this private.
+- `pk_*` — client-side publishable key. Restricted to browser-safe operations.
+
+## Usage Examples
+
+### Create and confirm a payment
+
+```typescript
+// Create with confirm: true to skip a separate confirm call
+const payment = await delopay.payments.create({
+  amount: 2500,
+  currency: 'EUR',
+  confirm: true,
+  capture_method: 'automatic',
+  payment_method: 'card',
+  payment_method_data: {
+    card: {
+      card_number: '4242424242424242',
+      card_exp_month: '12',
+      card_exp_year: '2030',
+      card_cvc: '123',
+    },
+  },
+  customer_id: 'cus_abc123',
+  description: 'Premium subscription',
+  return_url: 'https://example.com/checkout/complete',
+});
+
+// Or create first, then confirm separately
+const pending = await delopay.payments.create({
+  amount: 2500,
+  currency: 'EUR',
+  description: 'Premium subscription',
+});
+
+const confirmed = await delopay.payments.confirm(pending.payment_id, {
+  payment_method: 'card',
+  payment_method_data: {
+    card: {
+      card_number: '4242424242424242',
+      card_exp_month: '12',
+      card_exp_year: '2030',
+      card_cvc: '123',
+    },
+  },
+  return_url: 'https://example.com/checkout/complete',
+});
+
+console.log(confirmed.status); // 'succeeded' | 'requires_customer_action' | …
+```
+
+### Create a refund
+
+```typescript
+const refund = await delopay.refunds.create({
+  payment_id: 'pay_abc123',
+  amount: 1000, // partial refund; omit for full refund
+  reason: 'Customer request',
+});
+
+console.log(refund.refund_id, refund.status);
+```
+
+### Manage customers
+
+```typescript
+const customer = await delopay.customers.create({
+  name: 'Jane Doe',
+  email: 'jane@example.com',
+  metadata: { plan: 'pro' },
+});
+
+// List saved payment methods
+const methods = await delopay.paymentMethods.list(customer.customer_id);
+
+// Use a saved method on a new payment
+const payment = await delopay.payments.create({
+  amount: 1000,
+  currency: 'EUR',
+  customer_id: customer.customer_id,
+  payment_token: methods[0]?.payment_token,
+  confirm: true,
+});
+```
+
+### Handle disputes
+
+```typescript
+const disputes = await delopay.disputes.list({ payment_id: 'pay_abc123' });
+
+for (const dispute of disputes) {
+  console.log(dispute.dispute_id, dispute.dispute_stage, dispute.dispute_status);
+}
+```
+
+### Manage shops and gateways
+
+```typescript
+// Create a shop (business profile)
+const shop = await delopay.shops.create(merchantId, {
+  shop_name: 'My Online Store',
+  webhook_url: 'https://example.com/webhooks/delopay',
+  return_url: 'https://example.com/checkout/complete',
+});
+
+// Connect Stripe as a payment gateway
+const gateway = await delopay.shops.gateways.connect(merchantId, shop.shop_id, {
+  connector_type: 'payment_processor',
+  connector_name: 'stripe',
+  connector_account_details: {
+    auth_type: 'HeaderKey',
+    api_key: process.env.STRIPE_SECRET_KEY,
+  },
+  test_mode: true,
+});
+
+// List connected gateways
+const gateways = await delopay.shops.gateways.list(merchantId, shop.shop_id);
+```
+
+### Webhook verification
+
+```typescript
+import { Delopay } from '@delopay/sdk';
+
+// In your Express handler:
+app.post('/webhooks/delopay', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['delopay-signature'] as string;
+  const secret = process.env.DELOPAY_WEBHOOK_SECRET!;
+
+  let event;
+  try {
+    event = Delopay.webhooks.verify(req.body.toString(), signature, secret);
+  } catch (err) {
+    return res.status(400).send('Invalid signature');
+  }
+
+  switch (event.type) {
+    case 'payment_succeeded':
+      // fulfill order
+      break;
+    case 'payment_failed':
+      // notify customer
+      break;
+    case 'refund_succeeded':
+      // update records
+      break;
+  }
+
+  res.json({ received: true });
+});
+```
+
+## Error Handling
+
+All errors are instances of `DelopayError`:
+
+```typescript
+import { Delopay, DelopayError, DelopayAuthenticationError } from '@delopay/sdk';
+
+try {
+  const payment = await delopay.payments.retrieve('pay_does_not_exist');
+} catch (err) {
+  if (err instanceof DelopayAuthenticationError) {
+    // status: 401 — invalid or missing API key
+    console.error('Check your API key');
+  } else if (err instanceof DelopayError) {
+    console.error(err.message); // human-readable message
+    console.error(err.status); // HTTP status code
+    console.error(err.code); // machine-readable error code
+    console.error(err.type); // error category (e.g. 'not_found')
+  }
+}
+```
+
+**Error classes:**
+
+| Class                        | When                               |
+| ---------------------------- | ---------------------------------- |
+| `DelopayError`               | Base class for all API errors      |
+| `DelopayAuthenticationError` | `401` — invalid or missing API key |
+
+Network timeouts throw `DelopayError` with `code: 'TIMEOUT'`. Network failures throw with `code: 'NETWORK'`.
+
+## TypeScript
+
+The SDK is written in strict TypeScript. All request and response shapes are fully typed. Import types directly when needed:
+
+```typescript
+import type { PaymentResponse, PaymentCreateRequest, Currency } from '@delopay/sdk';
+```
+
+## Environments
+
+| Environment | Base URL                      | API key prefix            |
+| ----------- | ----------------------------- | ------------------------- |
+| Production  | `https://api.delopay.net`     | `sk_live_*` / `pk_live_*` |
+| Sandbox     | `https://sandbox.delopay.net` | `sk_test_*` / `pk_test_*` |
+
+```typescript
+// Sandbox
+const delopay = new Delopay(process.env.DELOPAY_API_KEY!, { sandbox: true });
+```
+
+## License
+
+MIT