npm package: @keyvoy/node
Description: Server-side SDK for Keyvoy — manage users, wallets, and Daml transactions on Canton Network
Author: Cayvox Labs
Latest version: 0.1.0

# @keyvoy/node

Server-side SDK for [PartyLayer Enterprise](https://partylayer.com) — manage users, wallets, and Daml transactions on Canton Network from your backend.

> **Looking for the open-source wallet connector?** See [@partylayer/sdk](https://www.npmjs.com/package/@partylayer/sdk)

## Install

```bash
npm install @keyvoy/node
```

## Quick Start

```typescript
import PartyLayerNode from '@keyvoy/node';

const pl = new PartyLayerNode({
  apiKey: 'pk_live_...',
  // apiBaseUrl: 'https://api.partylayer.io/v1', // default
});

// Create a user with embedded wallet
const user = await pl.users.create({
  email: 'alice@example.com',
  auth0Id: 'auth0|abc123',
});

// List users with filtering
const { data: users, total } = await pl.users.list({
  page: 1,
  pageSize: 20,
  trustLevel: 'embedded',
});

// Submit a Daml transaction on behalf of a user
const result = await pl.wallets.submitTransaction(user.id, {
  templateId: 'Cayvox.PartyLayer.RewardDelegation:RewardDelegation',
  choice: 'ClaimReward',
  args: { amount: '100' },
  contractId: '00abc...',
});

// Create a webhook endpoint
const webhook = await pl.webhooks.create({
  url: 'https://your-server.com/webhooks',
  events: ['user.created', 'tx.completed'],
});
console.log(webhook.secret); // whsec_... (shown once)
```

## Webhook Verification

Verify incoming webhooks in your Express/Hono/Fastify server:

```typescript
import { verifyWebhookSignature } from '@keyvoy/node';
// or: import { WebhooksResource } from '@keyvoy/node';

const isValid = verifyWebhookSignature(
  req.headers['x-partylayer-signature'],
  rawBody,
  'whsec_...',
  parseInt(req.headers['x-partylayer-timestamp']),
);
```

## Error Handling

```typescript
import {
  PartyLayerNotFoundError,
  PartyLayerAuthError,
  PartyLayerRateLimitError,
} from '@keyvoy/node';

try {
  await pl.users.get('usr_nonexistent');
} catch (err) {
  if (err instanceof PartyLayerNotFoundError) {
    console.log('User not found');
  } else if (err instanceof PartyLayerAuthError) {
    console.log('Invalid API key');
  } else if (err instanceof PartyLayerRateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  }
}
```

## API Reference

### Resources

| Resource | Methods |
|----------|---------|
| `pl.users` | `list`, `get`, `create`, `delete` |
| `pl.apps` | `list`, `get`, `create`, `update`, `delete` |
| `pl.wallets` | `get`, `submitTransaction`, `getContracts` |
| `pl.webhooks` | `list`, `create`, `delete` |
| `pl.apiKeys` | `list`, `create`, `revoke` |

### Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | — | **Required.** Your PartyLayer API key |
| `apiBaseUrl` | `string` | `https://api.partylayer.io/v1` | API base URL |
| `timeout` | `number` | `30000` | Request timeout (ms) |
| `maxRetries` | `number` | `3` | Retry attempts for 429/503 |

## Documentation

Full docs at [docs.partylayer.com](https://docs.partylayer.com)

## License

MIT © [Cayvox Labs](https://cayvox.com)