Add Bambuddy InvenTree sync service

README.md

@@ -0,0 +1,110 @@
+# 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"
+```
+
+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`.
+
+## 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.