# kdbx-lib

TypeScript wrapper around `pykeepass` for reading and modifying KeePass `.kdbx` files.

## Overview

This project uses:
- TypeScript as the public API
- Python as the runtime backend
- `pykeepass` to read and update KeePass databases

The TypeScript layer launches a Python bridge per request and exchanges JSON through stdin/stdout.

## Requirements

- Node.js or Bun
- Python 3
- `pykeepass` installed in the Python environment used by the bridge (the project provides `bun run setup:python`)
- The bridge defaults to `.venv/bin/python3`, or you can override with `PYTHON_PATH`

## Python setup

Install `pykeepass` in the Python environment used by the bridge:

```bash
bun run setup:python
```

If you prefer manual installation:

```bash
python3 -m venv .venv && .venv/bin/pip install pykeepass
```

The bridge also works with a project-local virtual environment such as `.venv`.

## Usage

```ts
import { openKeePassDatabase } from "./src/keepass";

const db = openKeePassDatabase("tests/fixtures/data.kdbx", {
	password: "123",
});

const entries = await db.listEntries();
console.log(entries);
```

## Example

Run the example using the bundled data fixture credentials:

```bash
bun run src/example.ts
```

## API

### `openKeePassDatabase(path, options)`

Creates a database wrapper.

#### Options
- `password`: KeePass master password
- `keyFile`: optional key file path

### `listEntries()`
Returns all entries in the database, with every entry field exposed by the bridge (`title`, `username`, `password`, `url`, `notes`, `groupPath`, `otp` when present).

### `findEntries(query)`
Finds entries by partial match and returns the full entry objects.

### `listGroups()`
Returns all groups, including their names and paths.

### `createEntry(entry)`
Creates a new entry in the target database and persists it immediately.

#### Entry input
- `title`: entry title
- `username`: optional username
- `password`: optional password
- `url`: optional URL
- `notes`: optional notes
- `groupPath`: optional target group path

### `createGroup(group)`
Creates a new group and persists it immediately.

#### Group input
- `name`: group name
- `path`: optional parent group path

### `save()`
Persists the current database state.

### `close()`
No-op for now.

## Notes

- The bridge currently launches a Python process per call.
- This is simple and robust for a first version.
- Errors from the Python bridge are propagated to the TypeScript API, including invalid or empty output.
- A persistent Python process can be added later if needed.
- Write operations currently open, modify, and save the database per command.
- Bundled fixtures include `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx`; the companion JSON file stores the password and expected content for tests/examples.
- Integration tests validate the bundled `data.kdbx` entry-by-entry and group-by-group against `tests/fixtures/data.kdbx.json`, and may skip cleanly when `pykeepass` is unavailable.