# Installation

Install and configure the HivePay SDK for your project.

---

## Package Installation

+++ pnpm
```bash
pnpm add @hivepay/client
```
+++ npm
```bash
npm install @hivepay/client
```
+++ yarn
```bash
yarn add @hivepay/client
```
+++ bun
```bash
bun add @hivepay/client
```
+++ Composer (PHP)
```bash
composer require hivepay/client
```
+++

---

## ESM Import

The SDK is distributed as an ESM module:

+++ TypeScript
```typescript
import { HivePay } from '@hivepay/client';
```
+++ JavaScript (ESM)
```javascript
import { HivePay } from '@hivepay/client';
```
+++ JavaScript (CommonJS)
```javascript
const { HivePay } = require('@hivepay/client');
```
+++

---

## Creating a Client

### With API Key

Most operations require an API key:

+++ TypeScript
```typescript
import { HivePay } from '@hivepay/client';

const hivepay = new HivePay({
  apiKey: 'sk_live_xxxxxxxxxxxxx'
});
```
+++

### Without API Key

Registration doesn't require an API key:

+++ TypeScript
```typescript
import { HivePay } from '@hivepay/client';

// Create public client
const publicClient = new HivePay();

// Register a merchant
const result = await publicClient.merchants.register({
  name: 'My Store',
  hiveAccount: 'mystore'
});

// Create authenticated client from result
const authClient = publicClient.withApiKey(result.apiKey);
```
+++

---

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | - | Your HivePay API key |
| `webhookSecret` | `string` | - | Webhook signing secret (`whsec_xxx`) for signature verification |
| `endpoint` | `string` | `https://hivepay.me` | API endpoint URL |
| `timeout` | `number` | `30000` | Request timeout in ms |

### Full Configuration

+++ TypeScript
```typescript
const hivepay = new HivePay({
  apiKey: 'sk_live_xxxxxxxxxxxxx',
  webhookSecret: 'whsec_xxxxxxxxxxxxx',  // For webhook verification
  endpoint: 'https://hivepay.me',         // Default
  timeout: 30000                           // 30 seconds
});
```
+++

### Custom Endpoint

For self-hosted deployments:

+++ TypeScript
```typescript
const hivepay = new HivePay({
  apiKey: 'sk_live_xxxxxxxxxxxxx',
  endpoint: 'https://your-hivepay-instance.com'
});
```
+++

---

## Environment Variables

Store your API key securely using environment variables:

+++ TypeScript
```typescript
// .env
HIVEPAY_API_KEY=sk_live_xxxxxxxxxxxxx
HIVEPAY_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

// app.ts
import { HivePay } from '@hivepay/client';

const hivepay = new HivePay({
  apiKey: process.env.HIVEPAY_API_KEY!,
  webhookSecret: process.env.HIVEPAY_WEBHOOK_SECRET!
});
```
+++ JavaScript
```javascript
require('dotenv').config();
const { HivePay } = require('@hivepay/client');

const hivepay = new HivePay({
  apiKey: process.env.HIVEPAY_API_KEY,
  webhookSecret: process.env.HIVEPAY_WEBHOOK_SECRET
});
```
+++

---

## TypeScript Configuration

The SDK includes TypeScript definitions. No additional `@types` package is needed.

Recommended `tsconfig.json` settings:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true
  }
}
```

---

## Browser Usage

The SDK works in modern browsers with native `fetch` support:

```html
<script type="module">
  import { HivePay } from 'https://esm.sh/@hivepay/client';

  const hivepay = new HivePay({ apiKey: 'sk_live_xxx' });
  // ...
</script>
```

!!!warning Security Warning
Never expose your API key in client-side code! Use a backend server to create payments, then pass the checkout URL to the frontend.
!!!

---

## Verifying Installation

Test your installation:

+++ TypeScript
```typescript
import { HivePay } from '@hivepay/client';

const hivepay = new HivePay({ apiKey: process.env.HIVEPAY_API_KEY! });

async function testConnection() {
  try {
    const merchant = await hivepay.merchants.getCurrent();
    console.log('Connected as:', merchant.name);
  } catch (error) {
    console.error('Connection failed:', error);
  }
}

testConnection();
```
+++

---

## Next Steps

- [Payments API](/sdk/payments/) - Create and manage payments
- [Merchants API](/sdk/merchants/) - Manage merchant accounts
- [Billing API](/sdk/billing/) - Read your monthly billing summary and outstanding invoices
- [Error Handling](/sdk/errors/) - Handle errors gracefully