Beans API #61

can we change bean_brand to 'roaster' perhaps? Or maybe I need more context about what is the difference between
bean_brand, bean_type and bean_variety.
And maybe a bean_density field would be interesting?
Or we can have a free-form metadata field here as well

Do you see beans, equipment, grinders being a plugin with a database that drives selection of shot meta data?

I'd love to get beanconquerer to offer a feature to publish to these endpoints to populate a bean inventory. I use BQ to manage my bean inventory today and doing things there and in DYE is cumbersome. If I could publish from BQ to this, or just transition all bean inventory to this plugin since I can access it from other devices than the machine tablet. (assuming there is UI that offers that)

BQ is very mature, flexible, well-supported, and has a ton of options. I'd almost rather he port BQ to a streamline bridge plugin!

Was reading through the data schema and had a couple thoughts if I may chime in.

• I am blown away at how comprehensive and thought out it is. You have done your homework and I love the initiation to the other key players in this space. Great support from the community.
• do people really unfreeze beans before using them? or is that just capturing the grind date or brew date?
• please capture decaf as a bean field (up to you if you want to capture the styles of decaf)
• The way BQ does bag splits of partial bag freezing, and consumption of a frozen bag is nice (personally I use tubes and grind straight from the freezer) I understand for 5 people you will have 6 different workflows. Just wanted to mention it since there are notes about it.
• There are bags that combine species (Saka DEK) Not sure how common this is if its even worth accommodating.

Thanks!

@apaperclip Yes, I sometimes unfreeze bags before using them.

@tadelv - endpoints for frozen status and freeze date. It could be a skin support thing too. Are you done with bean/batch development for all that you've planned?

Thanks!

I see above and in the schema that freeze date is listed but when I do a get on the batch id

curl -X 'GET' \
 'http://localhost:8080/api/v1/bean-batches/68724bca-6421-4bd7-88b8-4cf843d1b1ed' \
 -H 'accept: application/json'

freeze date (and others are not listed)

{
 "id": "68724bca-6421-4bd7-88b8-4cf843d1b1ed",
 "beanId": "9bbc55b5-b645-4ae5-b6ac-96926e13f3ae",
 "roastDate": "2025-07-09T00:46:19.177Z",
 "roastLevel": "string",
 "qualityScore": 0,
 "price": 0,
 "currency": "string",
 "weight": 0,
 "weightRemaining": 0,
 "frozen": true,
 "archived": false,
 "notes": "string",
 "createdAt": "2026-06-27T15:02:57.598287",
 "updatedAt": "2026-07-08T20:48:59.388772",
 "extras": {
 "additionalProp1": {}
 }
}

If I try a PUT and include set it, I get a 200 OK back but I can't verify it since the batch id GET doesn't include it in the output.

Thanks for the report @apaperclip! I've traced through the code and confirmed the issue — the handler in beans_handler.dart doesn't parse freezeDate, unfreezeDate, frozen in _createBatch, and is missing harvestDate, buyDate, openDate, bestBeforeDate, freezeDate, and unfreezeDate in _updateBatch. The model, database, and mapper layers are all fine — it's purely a handler oversight.

Created #424 to track this: #424

I would like to extend this discussion with a concrete inventory and bean-entry proposal. This is exploratory and is intended to build on the existing Beans API rather than create a parallel bean model.

Current Decaid baseline

Decaid already models Bean and BeanBatch, including total weight and weightRemaining (model). The API documentation already describes weightRemaining as inventory (documentation). There is also a low-level decrement helper, but it currently reduces a single value and clamps at zero (DAO implementation).

That is enough for a displayed remainder, but not enough to explain or safely reconcile how it changed.

Reversible inventory ledger

Instead of treating weightRemaining as the only truth, record signed inventory events and derive/reconcile the current balance from them. An event would carry at least:

• bean batch;
• signed gram delta;
• kind: initial amount, completed shot, purge/waste, correction, restore;
• optional shot reference;
• timestamp and note;
• an idempotency key for shot-derived events.

Completed shots should consume ShotAnnotations.actualDoseWeight when present; Decaid already records that field (shot annotations). If no actual dose was entered, the active workflow's target dose can be used only as a visibly marked estimate. Canceled/failed shots should not consume beans automatically.

Editing, deleting, or reassigning a shot must reverse/reconcile its prior event rather than decrementing twice. Manual purge, waste, and correction entries remain possible. If the ledger goes below zero, preserve the event history and warn instead of silently losing information by clamping the value.

Archiving an empty batch should remain a user choice, perhaps prompted by the UI.

Camera-assisted bean entry

The tablet camera could reduce duplicate data entry through three paths:

1. Beanconqueror share QR: decode its existing protobuf bean-share link and show an editable import preview. The public implementation is here: Beanconqueror share service.
2. EAN/UPC barcode: first match local/imported records; if unknown, offer an optional remote lookup and preview the result.
3. Label photo: local OCR where practical, producing an editable draft rather than silently creating a bean.

Beanconqueror's bean model already has weight and EAN fields that can participate in interchange (bean schema).

Privacy should be local-first. Any uploaded barcode or image needs an explicit preview/consent step and must name the service receiving it. Manual entry remains the fallback.

Camera support also needs a real feasibility spike on the older Decent-provided tablets. Decaid's current Android manifest lists Bluetooth, notification, and network permissions but no camera permission (manifest).

Questions

1. Is a shot-linked reversible ledger acceptable as the source of inventory history?
2. Should target dose be used as an estimate when actual dose is absent, or should automatic consumption require an actual dose?
3. Where should purge/waste/correction entry live so it remains quick enough for daily use?
4. Which remote barcode service, if any, is acceptable as an opt-in fallback?
5. Which Decent tablet generations should camera scanning support?

I opened a separate discussion for the interchange contract, roaster-published recommendations, and machine profiles: #721 Beanconqueror and roaster interoperability