# Brickset LEGO Plugin

An Obsidian plugin that integrates with the Brickset API to fetch LEGO set information and formatted notes with set details and images.

## Features

- **Fetch LEGO Sets by Number** - Simply enter a set number to retrieve complete set information
- **Automatic Note Creation** - Creates formatted markdown notes with all set details
- **Image Integration** - Downloads and embeds set images directly in your notes
- **Rich Set Data** - Includes pieces, minifigs, pricing, ratings, and more
- **Metadata Support** - Adds frontmatter tags for easy organization

## Installation

### From Obsidian Community Plugins

1. Open Obsidian Settings
2. Navigate to Community Plugins
3. Search for "LEGO"
4. Click Install
5. Enable the plugin

### Manual Installation

1. Download the latest release from GitHub
2. Extract the files to your vault's `.obsidian/plugins/brickset-lego/` folder
3. Reload Obsidian
4. Enable the plugin in Settings → Community Plugins

## Setup

### 1. Configure the Plugin

1. Open Obsidian Settings
2. Navigate to Plugin Options → Brickset
3. (Optional) Configure the folder where LEGO set notes will be created
4. (Optional) Enter your Brickset username and password for personalized features
5. Click "Save Settings"

## Usage

### Fetch a LEGO Set

1. Open the Command Palette (`Cmd/Ctrl + P`)
2. Type "Fetch LEGO Set" and select the command
3. Enter the LEGO set number
4. Press Enter

The plugin will:
- Fetch the set data from Brickset
- Download set images
- Create a new note with all information
- Open the note for you to view

### Example Set Numbers to Try

- `75192` - Millennium Falcon (UCS)
- `10497` - Galaxy Explorer
- `42143` - Ferrari Daytona SP3
- `10316` - Rivendell

## Note Format

Each LEGO set note includes:

```markdown
---
tags: lego, set
setNumber: 75192
theme: Star Wars
year: 2017
pieces: 7541
---

# 75192: Millennium Falcon

![Set Image](image-url)

## Details
- **Set Number:** 75192
- **Name:** Millennium Falcon
- **Theme:** Star Wars
- **Subtheme:** Ultimate Collector Series
- **Year Released:** 2017
- **Pieces:** 7541
- **Minifigs:** 8
- **RRP:** $799.99
- **Rating:** 4.8/5

## Description
The full set description fetched from Brickset appears here.

## Additional Images
![Additional Image 1](images/additional-1.jpg)
![Additional Image 2](images/additional-2.jpg)

## Links
- [Brickset Page](https://brickset.com/sets/75192-1)

## Notes
<!-- Add your personal notes here -->
```

## Settings

### Optional Settings

- **LEGO Sets Folder** - Folder where notes will be created (default: "LEGO Sets")
- **Brickset Username** - Your Brickset username (for personalized features)
- **Brickset Password** - Your Brickset password (for personalized features)

## Troubleshooting

### "Set Not Found" Error

- Verify the set number is correct
- Try searching on [Brickset.com](https://brickset.com) first
- Some very new or unreleased sets may not be available

### Images Not Loading

- Check your internet connection
- Verify the vault has write permissions
- Try fetching the set again

## Privacy & Security

### Network and background behavior

This plugin does not send periodic telemetry or background beacons. A short internal timer runs while the plugin is enabled only to save a local JSON cache file inside the plugin folder (`state-cache.json`) so bidirectional sync can detect your edits. That timer performs vault disk I/O only and does not open network connections.

Data is sent to Brickset’s API over HTTPS only when you choose actions that require it, for example:

- Logging in from settings
- Running **Fetch LEGO Set**
- Running **Sync LEGO collection from Brickset**
- With **Enable bidirectional sync** turned on, updating qualifying fields in a LEGO note’s frontmatter (after the configured delay)

Enabling the plugin alone does not start collection-wide or bidirectional API traffic; those depend on the commands and toggles above.

### Credentials and encryption

- No data is sent to any server except Brickset's official API.
- Optional username and password are stored in plaintext on the assumption that your Obsidian vault stays on a machine you control. (You could instead avoid storing the password and re-enter it when the session hash expires.)
- All API calls use HTTPS.

## Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/mirkostanic/obsidian-lego.git
cd obsidian-lego

# Install dependencies
npm install

# Build the plugin
npm run build

# Development mode (auto-rebuild on changes)
npm run dev

# Run tests
npm run test

# Run tests and show coverage
npm run test:coverage

# Run lint
npm run lint

# Run lint and attempt fix
npm run lint:fix

# Bump version
npm version X.Y.Z
npm run version
```

### Project Structure

```
obsidian-lego/
├── src/
│   ├── main.ts              # Main plugin class
│   ├── settings.ts          # Settings tab + persistence
│   ├── stateCache.ts        # On-disk cache of previously synced frontmatter
│   ├── syncBackService.ts   # Obsidian → Brickset bidirectional sync
│   ├── syncService.ts       # Brickset → Obsidian collection sync
│   ├── bricksetApi.ts       # Brickset HTTP API service
│   ├── types.ts             # Type definitions
│   ├── noteCreator.ts       # Note generation
│   └── modal.ts             # User input modal
├── manifest.json            # Plugin manifest
├── package.json             # Dependencies
├── styles.css               # Styling
└── README.md                # This file
```

## Contributing

Contributions are welcome. Please feel free to submit a Pull Request.

### Development Guidelines

1. Follow TypeScript best practices
2. Add tests for new features
3. Update documentation
4. Follow the existing code style

## Support

- [Documentation](https://github.com/mirkostanic/obsidian-lego/wiki)
- [Report Issues](https://github.com/mirkostanic/obsidian-lego/issues)
- [Discussions](https://github.com/mirkostanic/obsidian-lego/discussions)

## Credits

- Built for [Obsidian](https://obsidian.md)
- Data provided by [Brickset](https://brickset.com)
- LEGO® is a trademark of the LEGO Group

## Tests

```bash
npm test              # Run all tests once
npm run test:watch    # Watch mode for development
npm run test:coverage # Generate coverage report
```

## License

MIT License - see LICENSE file for details

## Disclaimer

This plugin is not affiliated with, endorsed by, or sponsored by the LEGO Group or Brickset. LEGO® is a trademark of the LEGO Group of companies which does not sponsor, authorize or endorse this plugin. See [DISCLAIMER.md](DISCLAIMER.md) for full text.