# Bambuddy InvenTree Sync

Small sidecar service for syncing Bambuddy `Archives` into InvenTree.

It currently:

- creates an InvenTree `Part` automatically when a printed model is first seen;
- creates one InvenTree `StockItem` for each synced Bambuddy archive;
- stores local sync state in SQLite to avoid duplicate stock items;
- accepts Bambuddy webhooks and can also backfill existing archives.

The first version intentionally treats one Bambuddy archive as one printed stock item. Later we can add plate parsing, multi-object quantity detection, filament costing, thumbnails, 3MF attachments, and mapping rules.

## Setup

1. Copy `.env.example` to `.env`.
2. Fill in:
   - `BAMBUDDY_BASE_URL`
   - `BAMBUDDY_API_KEY`
   - `INVENTREE_BASE_URL`
   - `INVENTREE_TOKEN`
   - `INVENTREE_PART_CATEGORY_ID`
   - `INVENTREE_STOCK_LOCATION_ID`
3. Start the service:

```powershell
docker compose up -d --build
```

The service listens on `http://localhost:8088`.

## InvenTree IDs

For the first version, use numeric IDs for the target InvenTree part category and stock location. Open the desired category/location in InvenTree and copy the ID from the URL or API response.

Example:

```env
INVENTREE_PART_CATEGORY_ID=12
INVENTREE_STOCK_LOCATION_ID=7
```

## Validate Connectivity

If `SERVICE_API_TOKEN` is set in `.env`, pass it as `X-Service-Token`:

```powershell
curl.exe -H "X-Service-Token: change-me" http://localhost:8088/validate
```

## Backfill Existing Archives

Run a test with one archive first:

```powershell
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/backfill?max_archives=1"
```

When `SYNC_SUCCESS_ONLY=true`, `max_archives` counts import attempts. Archives that are still `printing` or already failed are skipped and do not consume the limit.

Run full backfill for successful Bambuddy archives:

```powershell
curl.exe -X POST -H "X-Service-Token: change-me" http://localhost:8088/sync/backfill
```

The default behavior is `SYNC_SUCCESS_ONLY=true`, so failed or stopped prints are not imported.

## Bambuddy Webhook

In Bambuddy, configure a webhook to:

```text
http://WINDOWS-SERVER-IP:8088/webhooks/bambuddy
```

If `WEBHOOK_SHARED_SECRET` is configured, Bambuddy must send this header:

```text
X-Sync-Secret: your-secret
```

The service expects Bambuddy payloads with `event=print_complete` and `data.archive_id`.

## Part Matching

The service builds a stable key from:

```env
PART_KEY_FIELDS=filename,name
```

That key becomes an InvenTree IPN:

```text
BMB-<first-12-sha1-chars>
```

This means repeat prints of the same file/name reuse the same `Part` and create new `StockItem` rows. To change matching behavior later, edit `PART_KEY_FIELDS`.

## InvenTree Part Parameters

For each synced `Part`, the service updates these InvenTree parameters when matching parameter templates exist:

- `Weight`: filament weight per printed item in grams. If a Bambuddy archive has `quantity=2`, the total filament weight is divided by 2.
- `PrintTime`: print duration from Bambuddy. The visible value is formatted as `1h 6m 1s`; `data_numeric` stores the duration in seconds.

## InvenTree Part Images

When `SYNC_PART_IMAGES=true`, the service downloads the Bambuddy archive thumbnail and uploads it to the InvenTree `Part.image` field.

By default, existing InvenTree part images are preserved:

```env
OVERWRITE_PART_IMAGES=false
```

Set `OVERWRITE_PART_IMAGES=true` if Bambuddy thumbnails should replace existing part images.

## Bambuddy External Links

When `SYNC_ARCHIVE_EXTERNAL_LINK=true`, the service writes the InvenTree part page URL into Bambuddy archive `external_url`.

The default link format is:

```text
<INVENTREE_WEB_URL or INVENTREE_BASE_URL>/web/part/<part_id>/
```

Existing non-InvenTree external links are preserved unless:

```env
OVERWRITE_ARCHIVE_EXTERNAL_LINK=true
```

## Useful Endpoints

```text
GET  /health
GET  /sync/status
GET  /validate
POST /sync/archive/{archive_id}
POST /sync/backfill
POST /webhooks/bambuddy
```

Manual sync endpoints require `X-Service-Token` when `SERVICE_API_TOKEN` is set.