npm package: @mongolian-payment/storepay
Description: StorePay payment SDK for Node.js - Create loans, check loan status, query user possible amounts
Latest version: 1.0.0

# @mongolian-payment/storepay

TypeScript SDK for the [StorePay](https://storepay.mn) payment provider. Zero dependencies, dual ESM/CJS builds, automatic OAuth2 token management.

## Installation

```bash
npm install @mongolian-payment/storepay
```

Requires Node.js >= 18.0.0 (uses native `fetch` and `btoa`).

## Quick Start

```typescript
import { StorePayClient } from "@mongolian-payment/storepay";

const client = new StorePayClient({
  appUsername: "your-app-username",
  appPassword: "your-app-password",
  username: "your-basic-auth-username",
  password: "your-basic-auth-password",
  authUrl: "https://auth.storepay.mn",
  baseUrl: "https://api.storepay.mn",
  storeId: "your-store-id",
  callbackUrl: "https://your-site.com/callback",
});

// Create a loan
const loanId = await client.loan({
  description: "Order #1234",
  mobileNumber: "99001122",
  amount: 50000,
});

// Check loan status
const confirmed = await client.loanCheck(String(loanId));

// Get user's possible loan amount
const possibleAmount = await client.userPossibleAmount("99001122");

// Clear cached tokens when done
client.close();
```

## Configuration from Environment

```typescript
import { StorePayClient, loadConfigFromEnv } from "@mongolian-payment/storepay";

const client = new StorePayClient(loadConfigFromEnv());
```

Required environment variables:

| Variable | Description |
|---|---|
| `STOREPAY_APP_USERNAME` | OAuth app username |
| `STOREPAY_APP_PASSWORD` | OAuth app password |
| `STOREPAY_USERNAME` | Basic Auth username |
| `STOREPAY_PASSWORD` | Basic Auth password |
| `STOREPAY_AUTH_URL` | Auth server URL |
| `STOREPAY_BASE_URL` | API base URL |
| `STOREPAY_STORE_ID` | Merchant store ID |
| `STOREPAY_CALLBACK_URL` | Callback URL for notifications |

## API Reference

### `new StorePayClient(config)`

Creates a new StorePay client. Authentication is handled automatically on the first API call.

### `client.loan(input): Promise<number>`

Create a loan request. Returns the loan ID.

- `input.description` - Description of the loan
- `input.mobileNumber` - Customer mobile number
- `input.amount` - Loan amount (number)

### `client.loanCheck(id): Promise<boolean>`

Check the status of a loan. Returns `true` if confirmed.

- `id` - The loan ID (string)

### `client.userPossibleAmount(mobileNumber): Promise<number>`

Get the maximum possible loan amount for a user.

- `mobileNumber` - The user's mobile number

### `client.close(): void`

Clear cached authentication tokens. Call this when the client is no longer needed.

## Error Handling

All API errors are thrown as `StorePayError` instances:

```typescript
import { StorePayClient, StorePayError } from "@mongolian-payment/storepay";

try {
  const loanId = await client.loan({ ... });
} catch (err) {
  if (err instanceof StorePayError) {
    console.error(err.message);     // Human-readable message
    console.error(err.statusCode);  // HTTP status code (if available)
    console.error(err.response);    // Raw API response (if available)
  }
}
```

## License

MIT