npm package: @jah-dev/securevault
Description: Node.js client for SecureVault - secure secrets management
Author: JahDev
Latest version: 0.1.0

# @jahdev/securevault

Node.js client for SecureVault - secure secrets management.

## Installation

```bash
npm install @jahdev/securevault
```

Or with yarn:

```bash
yarn add @jahdev/securevault
```

## Prerequisites

- SecureVault CLI must be installed and available in your PATH
- Node.js 14 or higher

## Quick Start

```javascript
const { VaultClient } = require('@jahdev/securevault');

async function main() {
    const vault = new VaultClient();
    
    // Set a secret
    await vault.set('api_key', 'my-secret-key');
    
    // Get a secret
    const apiKey = await vault.get('api_key');
    console.log(`API Key: ${apiKey}`);
    
    // List all secrets
    const secrets = await vault.list();
    console.log(`Secrets: ${secrets}`);
    
    // Delete a secret
    await vault.delete('api_key');
}

main().catch(console.error);
```

## TypeScript Support

This package includes TypeScript definitions:

```typescript
import { VaultClient, VaultError, SecretNotFoundError } from '@jahdev/securevault';

const vault = new VaultClient();

try {
    const apiKey: string = await vault.get('api_key');
    console.log(apiKey);
} catch (error) {
    if (error instanceof SecretNotFoundError) {
        console.error('Secret not found');
    }
}
```

## Usage Examples

### Basic Operations

```javascript
const { VaultClient } = require('@jahdev/securevault');

const vault = new VaultClient();

// Set with description
await vault.set('github_token', 'ghp_xxxxx', {
    description: 'GitHub Personal Access Token'
});

// Check if exists
if (await vault.exists('github_token')) {
    console.log('Token is configured');
}

// Get all secrets
const allSecrets = await vault.getAll();
console.log(allSecrets);
// { github_token: 'ghp_xxxxx', api_key: 'secret123' }
```

### Load into Environment

```javascript
const { VaultClient } = require('@jahdev/securevault');

const vault = new VaultClient();

// Load all secrets as environment variables
await vault.loadEnv();

// Access from process.env
console.log(process.env.API_KEY);

// Load with prefix
await vault.loadEnv({ prefix: 'APP_' });
console.log(process.env.APP_API_KEY);
```

### Export/Import

```javascript
const { VaultClient } = require('@jahdev/securevault');

const vault = new VaultClient();

// Export to JSON
await vault.exportToFile('./secrets.json');

// Import from JSON
await vault.importFromFile('./secrets.json');
```

### Express.js Integration

```javascript
const express = require('express');
const { VaultClient } = require('@jahdev/securevault');

const app = express();
const vault = new VaultClient();

// Middleware to load secrets
app.use(async (req, res, next) => {
    try {
        await vault.loadEnv({ prefix: 'VAULT_' });
        next();
    } catch (error) {
        res.status(500).json({ error: 'Failed to load secrets' });
    }
});

app.get('/api/config', async (req, res) => {
    try {
        const apiKey = await vault.get('api_key');
        res.json({ configured: true });
    } catch (error) {
        res.status(404).json({ configured: false });
    }
});

app.listen(3000);
```

### Custom CLI Path

```javascript
const { VaultClient } = require('@jahdev/securevault');

const vault = new VaultClient({
    cliPath: '/custom/path/to/securevault'
});
```

### Error Handling

```javascript
const { VaultClient, VaultError, SecretNotFoundError } = require('@jahdev/securevault');

const vault = new VaultClient();

try {
    const secret = await vault.get('nonexistent');
} catch (error) {
    if (error instanceof SecretNotFoundError) {
        console.error('Secret not found');
    } else if (error instanceof VaultError) {
        console.error('Vault error:', error.message);
    } else {
        console.error('Unexpected error:', error);
    }
}
```

### Async/Await with Multiple Operations

```javascript
const { VaultClient } = require('@jahdev/securevault');

async function setupSecrets() {
    const vault = new VaultClient();
    
    // Set multiple secrets
    await Promise.all([
        vault.set('db_host', 'localhost'),
        vault.set('db_user', 'admin'),
        vault.set('db_password', 'secret123')
    ]);
    
    // Retrieve all at once
    const [host, user, password] = await Promise.all([
        vault.get('db_host'),
        vault.get('db_user'),
        vault.get('db_password')
    ]);
    
    console.log(`Database: ${user}@${host}`);
}

setupSecrets().catch(console.error);
```

## API Reference

### `VaultClient`

#### Constructor

```javascript
new VaultClient(options?)
```

**Options:**
- `cliPath` (string, optional): Path to the securevault CLI. Default: `'securevault'`

#### Methods

##### `get(name)`

Get a secret value.

- **Parameters:** `name` (string) - Secret name
- **Returns:** `Promise<string>` - Secret value
- **Throws:** `SecretNotFoundError`, `VaultError`

##### `set(name, value, options?)`

Set a secret value.

- **Parameters:**
  - `name` (string) - Secret name
  - `value` (string) - Secret value
  - `options` (object, optional)
    - `description` (string) - Secret description
- **Returns:** `Promise<void>`
- **Throws:** `VaultError`

##### `delete(name)`

Delete a secret.

- **Parameters:** `name` (string) - Secret name
- **Returns:** `Promise<void>`
- **Throws:** `VaultError`

##### `list()`

List all secret names.

- **Returns:** `Promise<string[]>` - Array of secret names
- **Throws:** `VaultError`

##### `exists(name)`

Check if a secret exists.

- **Parameters:** `name` (string) - Secret name
- **Returns:** `Promise<boolean>` - True if exists
- **Throws:** `VaultError`

##### `getAll()`

Get all secrets as an object.

- **Returns:** `Promise<Object>` - Object mapping names to values
- **Throws:** `VaultError`

##### `loadEnv(options?)`

Load secrets into environment variables.

- **Parameters:**
  - `options` (object, optional)
    - `prefix` (string) - Prefix for variable names
- **Returns:** `Promise<void>`
- **Throws:** `VaultError`

##### `exportToFile(filepath)`

Export secrets to JSON file.

- **Parameters:** `filepath` (string) - Output file path
- **Returns:** `Promise<void>`
- **Throws:** `VaultError`

##### `importFromFile(filepath)`

Import secrets from JSON file.

- **Parameters:** `filepath` (string) - Input file path
- **Returns:** `Promise<void>`
- **Throws:** `VaultError`

## Development

### Running Tests

```bash
npm test
```

### Watch Mode

```bash
npm run test:watch
```

## License

MIT

## Author

JahDev