Beans API

[tadelv]

Beans management, bag management, etc.

Beans
bean_brand [Already on DE1]
bean_type [Already on DE1]
bean_notes [Already on DE1]
bean_country
bean_region
bean_variety
bean_producer
bean_altitude
bean_processing

Beans batch
roast_date [Already on DE1]
roast_level [Already on DE1]
bean_harvest
bean_quality_score
bean_price
bean_freeze_date
bean_unfreeze_date
bean_open_date

A copy from basecamp, written by Enrique.

[tadelv]

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

[apaperclip]

I'm going to invoke Cunningham’s Law. I'm not an expert but here is how I see it.

I would agree, brand likely means roaster. i.e. bean_roaster
varietal is going to be like geisha, SL28, pink bourbon, etc
type to me, is arabica, robusta, etc.

[ebengoechea]

While I would agree un terms of pure naming, I would not modify fields that have existed for years in the Tcl app and already appear with those names on all shot files in the histories.

[tadelv]

@ebengoechea any specific reason for going with the historical names forward as well? In terms of compatibility, we could adopt an approach that is more self-documenting and explanatory, while having a mapping in place to convert from historical data?

[ebengoechea]

@ebengoechea any specific reason for going with the historical names forward as well? In terms of compatibility, we could adopt an approach that is more self-documenting and explanatory, while having a mapping in place to convert from historical data?

Nope, just to avoid the mental mapping of "old model" and "new model" for existing stuff such as shot files. I also think visualizer uses the existing variable names.

But I don't have strong feelings one way or the other. Your implementation choice.

[apaperclip]

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!

[apaperclip]

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!

[ebengoechea]

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

[apaperclip]

With the bag table, I felt bean inventory management was implied. I would expect to tag some amount of coffee as frozen and provide a frozen-on date. I would then consume from these 'bags/batches' like normal. All the other bean and batch/bag fields would apply.

Frozen and frozen data (or any other frozen-adjacent fields) would just be more bag/batch attributes in my mind.

I don't unfreeze, but others have chimed in they do.

I don't track blend compositions, but I'm sure others do.

[tadelv]

@apaperclip - just to make sure I understand completely, regarding frozen beans. You do not unfreeze them when preparing the coffee? They go straight from frozen -> ground, right?
We're trying to structure the API in a way that will allow for really complex combinations if needed, but also stay out of the way if all you want is to make coffee. To be honest, it's actually the skins' developer choice, how complex or simple they wish the bean (or other aux data) information to be.

[apaperclip]

@tadelv correct! I grind the frozen beans.

[apaperclip]

@tadelv do you plan to expose API management of all bean / batch properties?

[tadelv]

@apaperclip should already be possible with the current API endpoints. What functionality are you missing?

[apaperclip]

@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?

[tadelv]

check http://localhost:4001/#/Beans/get_api_v1_bean_batches__id_, but replace localhost with the ip of the device running Rea.

Here is the schema for a bean batch. Note it includes both fields:

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "beanId": "550e8400-e29b-41d4-a716-446655440000",
  "roastDate": "2026-07-08T19:56:03.301Z",
  "roastLevel": "medium-light",
  "harvestDate": "string",
  "qualityScore": 87.5,
  "price": 18.5,
  "currency": "EUR",
  "weight": 250,
  "weightRemaining": 180,
  "buyDate": "2026-07-08T19:56:03.301Z",
  "openDate": "2026-07-08T19:56:03.301Z",
  "bestBeforeDate": "2026-07-08T19:56:03.301Z",
  "freezeDate": "2026-07-08T19:56:03.301Z",
  "unfreezeDate": "2026-07-08T19:56:03.301Z",
  "frozen": false,
  "archived": false,
  "notes": "string",
  "createdAt": "2026-07-08T19:56:03.301Z",
  "updatedAt": "2026-07-08T19:56:03.301Z",
  "extras": {
    "additionalProp1": {}
  }
}

[apaperclip]

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.

[tadelv]

yes, you're right! I checked the source and we're indeed missing the updates for these fields, thanks a bunch! I'll create an issue for this. Sorry for lying to you 😅

[tadelv]

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

[apaperclip]

awesome! you are welcome and thank you

@giladger for bean batch modification support in the beanie skin.

[MaxRink]

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