0.4.0

[ad-ha]

Hi,

This is something that I had in mind from the beginning and went leaving aside, to get things moving forward, but as this is growing so much I believe we need to step back a moment and get it addressed.

For next 0.4.0 release, aside from the revamping of badges, I am also refactoring all hard-coded text and defaults to pull everything from constants. It will be easier to manage the whole code and changes, making it all more organic and manageable.

I just push a whole set of updates for const and flow_helpers. I will keep going with config_flow, options_flow and coordinator. These also include pulling constants generally and not individually on each file, which eases a lot the maintenance and coding.

I was thinking also into addressing some key issues with naming that, since I did some poor decisions not to breakdown by sections when I started this project, but as this may cause a lot of breaking changes or require a bigger migration, I may leave those aside as they are not as relevant.

This is a major manual task, which may take some time to get grips with, but I believe it will be worth of and pay off in the long run.

Cheers

[ccpk1]

I spent a little time looking through this and doing some quick analysis. As you might already know, I like standardization, and I'm happy to lend a hand with this. That said, before we go any further, I think we need to come up with a good process. If we just start individually adding a bunch of constants, I think it will lead to unnecessary duplication and complexity. My proposal is starting with a plan to organize and arrange the constant file before doing any more substitutions. Once aligned on how that should be structured, it will make it much easier to add one-off things that come up and ensure we're keeping it as simple as possible. (It is a bunch of work) I'll put together a quick high level overview.

One other clarification... Is your intent to replace the majority of all hard-coded text in those files? i.e. both the things that are programmatic, as well as the content that would be exposed to the user?

[ad-ha]

Hi,

Thanks for the availability tu help on this.

My goad is to move as much hard-coded text and defaults into consts.

I should have done this from the very beginning, in part I did, but after to ease I just started adding things and thought "I will do it after..." until it kept growing and growing. So maybe better doing this now.

The next task on my list is to do ConfigFlow, OptionsFlow and Coordinator. On this I will be trying to separate Data Labels from ConfOptions and Labels (as I did on flow_helpers). So yes, these would include frontend and programmatic items.

Mostly trying to mimic HA Quality of Scale requirements for Platinum. If we ever be able to get there.

Any ideas are welcome. I tried to standardize already a lot of things, but a different approach may make it easier.

Cheers

[ccpk1]

We could go about organizing this a few different ways, but considering that most work is grouped by component, that made the most sense to me at first pass. (i.e. grouped points, chores, rewards, etc.) I'm open to alternatives, just trying to think about how we can easily add on and scale as required.

Constants File Organization Outline

1. Core Integration Settings

Purpose: Store the fundamental integration details.

• General: Domain, Logging
• Defaults: Storage key, Version, Update interval

2. Configuration and Data Keys

Purpose: Include all configuration keys, integration‐level service commands, and persistent data keys.

• General: Configuration keys, options flow, settings, labels
• Services: Integration-level service commands (e.g., reset all data)
• Defaults: Default values that aren't in subsections below
• Data Keys: Persistent storage identifiers
• Errors & Validations: Generic configuration error messages not in subsections below

3. Points

Purpose: All constants related to points management.

• General: Points names, settings, labels
• Actions: Point adjustment actions/icons
• Sensors: Attributes for points sensors
• Services: Points-related service commands
• Defaults: Default points label, icon
• Errors & Validations: Errors regarding invalid point values

4. Kids

Purpose: Constants for kid-specific functionality.

• General: Kid names, person-level settings, labels (including HA user ID)
• Workflow & Notification: Kid-specific workflows and notification settings
• Actions: Actions available for kid entities
• Sensors: Sensors tracking kid-related data
• Services: Services that affect kid entries
• Defaults: Default values for kid configuration
• Errors & Validations: Error messages for kid data

5. Parents

Purpose: Constants for parent-specific functionality.

• General: Parent names, person-level settings, labels (including HA user ID)
• Workflow & Notification: Parent workflow details and approval notifications
• Actions: Parent-specific actions
• Sensors: Sensors for parent data
• Services: Services affecting parent entries
• Defaults: Default values for parent configuration
• Errors & Validations: Error messages for parent data

6. Chores

Purpose: All constants related to chore configuration and management.

• General: Chore names, types, settings, labels
• Scheduling: Due dates, recurrence, applicable days
• Workflow & Notification: Chore workflow steps, notifications
• Actions: Chore claim, approval, disapproval actions
• Sensors: Chore sensor attributes and types
• Services: Chore-related service commands (e.g., reset overdue chores)
• Defaults: Default points, applicable days, icons, etc.
• Errors & Validations: Duplicate chore, invalid due date, etc.

7. Rewards

Purpose: Constants for reward configuration and management.

• General: Reward names, settings, labels
• Workflow & Notification: Reward workflows and notifications
• Actions: Reward claim and approval actions
• Sensors: Reward sensor attributes
• Services: Reward-related services
• Defaults: Default reward cost, icons, etc.
• Errors & Validations: Invalid reward, duplicate reward errors

8. Bonus

Purpose: Constants for bonus-related functionality.

• General: Bonus names, settings, labels
• Workflow & Notification: Bonus application notifications
• Actions: Bonus-related actions
• Sensors: Bonus sensor attributes
• Services: Bonus-related service commands
• Defaults: Default bonus points, icons, etc.
• Errors & Validations: Invalid or duplicate bonus messages

9. Penalties

Purpose: Constants for penalty configuration and management.

• General: Penalty names, settings, labels
• Workflow & Notification: Penalty workflow notifications
• Actions: Penalty application actions
• Sensors: Penalty sensor attributes
• Services: Penalty-related services
• Defaults: Default penalty points, icons, etc.
• Errors & Validations: Errors for penalty misconfigurations

10. Badges

Purpose: Constants for badge creation and evaluation.

• General: Badge names, settings, labels, threshold types
• Workflow & Notification: Badge evaluation notifications
• Actions: Badge-related actions
• Sensors: Badge sensor attributes
• Services: Badge-related services
• Defaults: Default badge threshold, icons, etc.
• Errors & Validations: Badge configuration errors

11. Achievements

Purpose: Constants for achievement configuration and progress tracking.

• General: Achievement names, types, settings, labels
• Workflow & Notification: Achievement progress workflows and notifications
• Actions: Achievement-related actions
• Sensors: Achievement sensor attributes
• Services: Achievement-related services
• Defaults: Default achievement values
• Errors & Validations: Invalid achievement, duplicate achievement messages

12. Challenges

Purpose: Constants for defining and managing challenges.

• General: Challenge names, settings, labels
• Scheduling: Start/end dates, recurrence for challenges
• Workflow & Notification: Challenge workflow and notifications
• Actions: Challenge-related actions
• Sensors: Challenge sensor attributes
• Services: Challenge-related services
• Defaults: Default challenge values
• Errors & Validations: Challenge configuration errors

13. Deprecated Constants

Purpose: Constants slated for phase-out in future releases as we work through this process.

[ccpk1]

FYI - I'm just now seeing that you made a lot of changes to constants since I was looking at this earlier today. I'll have a look at that a little later because maybe you're heading in a little different direction which could be fine. I just want to ensure it's clear where everything should go and easily recognizable by the way it is grouped, named, or sorted. One thing I would add, is that there is a lot more misc. text to add as I looked through the config flow, so this is going to grow quite a bit.

[ad-ha]

My changes on const are broken in a different way than your proposal. Your idea seems good, but I would try to get together by key types, breaking down by section might be tricky in some parts, like sensor attributes, for example, where there are many similar ones.

Anyhow, as always, fully open to ideas and changes 👍

[ad-ha]

Adding to this, right now I would focus on the hard-coded code and potential translation keys. Everything else could be bumped after, but we may also look closely. Once the major constants are addressed everything else might be easier and faster to organize.

[ad-ha]

I need to get some rest. 😴

Left #140 with my latest changes, as I was testing the consts in the ConfigFlow and OptionsFlow to make sure menus would work fine.

[ad-ha]

Still a long way to go, but just replaced a few consts to make sure it works fine. Also, started organizing a bit the const file to get some order.

Feel free to go through and propose any ideas or changes

[ccpk1]

Looks like you've made a lot of progress and are probably pretty tired today! Sorry, I've been busy and haven't been able to jump in yet.

I did take a quick look through to get a feel for how you are structuring things. I see a lot of duplication, that I'm questioning whether it could or should be simplified. Or maybe it's because you are moving to a new standard like CFOF for config and options flow, but leaving the other constants in place until all the changes are made? Here are my questions:

1. As an example in the list below, is there value in having 3 constants for internal_id, or would it make more sense to have one DATA_INTERNAL_ID and then split it out to add another if it's needed in the future? Similar for kid_name, wouldn't it be easier and clearer to always use FIELD_KID_NAME. Again, maybe there is value in it, I'm just not clear on why they would be different.
2. If there are large groups of constants you plan to phase out, can we put them at the bottom under a "Phasing Out" header so I don't end up using them more? Or it would probably be easy enough to just do a global search and replace with matching case to just update to whatever the correct future name is in all files.
3. I'm a little hesitant to jump in and end up working on the same file as you. Once I'm clear on the first two questions, then maybe it would be best for you to tell me 1 or 2 files that you know you won't be working on that day? I'll probably have a little time this evening if you want some help.

Quick list of Potential Duplicate Constants:

• "internal_id":

  • CONF_INTERNAL_ID = "internal_id"
  • DATA_INTERNAL_ID = "internal_id"
  • CFOF_GLOBAL_INPUT_INTERNAL_ID = "internal_id"
    #Potential-Dup

• "kid_name":

  • CFOF_KIDS_INPUT_KID_NAME = "kid_name"
  • CONF_KIDNAME = "kid_name"
  • FIELD_KID_NAME = "kid_name"
    #Potential-Dup

• "parent_name":

  • CONF_PARENT_NAME = "parent_name"
  • FIELD_PARENT_NAME = "parent_name"
    #Potential-Dup

• "chore_name":

  • CONF_CHORE_NAME = "chore_name"
  • FIELD_CHORE_NAME = "chore_name"
    #Potential-Dup

• "ha_user":

  • CFOF_KIDS_INPUT_KID_HA_USER = "ha_user"
  • CONF_HA_USER = "ha_user"
  • DATA_HA_USER = "ha_user"
    #Potential-Dup

• "ha_user_id":

  • CONF_HA_USER_ID = "ha_user_id"
  • DATA_HA_USER_ID = "ha_user_id"
    #Potential-Dup

• "enable_mobile_notifications":

  • CFOF_KIDS_INPUT_KID_ENABLE_MOBILE_NOTIFICATIONS = "enable_mobile_notifications"
  • CONF_ENABLE_MOBILE_NOTIFICATIONS = "enable_mobile_notifications"
    #Potential-Dup

• "mobile_notify_service":

  • CFOF_KIDS_INPUT_KID_MOBILE_NOTIFY_SERVICE = "mobile_notify_service"
  • CONF_MOBILE_NOTIFY_SERVICE = "mobile_notify_service"
  • DATA_KID_MOBILE_NOTIFY_SERVICE = "mobile_notify_service"
    #Potential-Dup

• "enable_persistent_notifications":

  • CFOF_KIDS_INPUT_KID_ENABLE_PERSISTENT_NOTIFICATIONS = "enable_persistent_notifications"
  • CONF_ENABLE_PERSISTENT_NOTIFICATIONS = "enable_persistent_notifications"
    #Potential-Dup

• "description":

  • CONF_DESCRIPTION = "description"
  • ATTR_DESCRIPTION = "description"
  • ATTR_CAL_DESCRIPTION = "description"
    #Potential-Dup

• "due_date":

  • VALIDATION_DUE_DATE = "due_date"
  • CONF_DUE_DATE = "due_date"
  • DATA_DUE_DATE = "due_date"
  • ATTR_DUE_DATE = "due_date"
    #Potential-Dup

• "partial_allowed":

  • VALIDATION_PARTIAL_ALLOWED = "partial_allowed"
  • CONF_PARTIAL_ALLOWED = "partial_allowed"
  • ATTR_PARTIAL_ALLOWED = "partial_allowed"
    #Potential-Dup

• "recurring_frequency":

  • CONF_RECURRING_FREQUENCY = "recurring_frequency"
  • DATA_RECURRING_FREQUENCY = "recurring_frequency"
  • ATTR_RECURRING_FREQUENCY = "recurring_frequency"
    #Potential-Dup

• "cost":

  • FIELD_COST = "cost"
  • ATTR_COST = "cost"
    #Potential-Dup

• "assigned_kids":

  • CONF_ASSIGNED_KIDS = "assigned_kids"
  • DATA_ASSIGNED_KIDS = "assigned_kids"
    #Potential-Dup

• "badge_labels":

  • CONF_BADGE_LABELS = "badge_labels"
  • DATA_BADGE_LABELS = "badge_labels"
    #Potential-Dup

• "badge_name":

  • CONF_BADGE_NAME = "badge_name"
  • DATA_BADGE_NAME = "badge_name"
    #Potential-Dup

• "threshold_type":

  • VALIDATION_THRESHOLD_TYPE = "threshold_type"
  • ATTR_THRESHOLD_TYPE = "threshold_type"
  • DATA_BADGE_THRESHOLD_TYPE = "threshold_type"
    #Potential-Dup

• "reward_name":

  • CONF_REWARD_NAME = "reward_name"
  • FIELD_REWARD_NAME = "reward_name"
    #Potential-Dup

• "reward_points":

  • ATTR_REWARD_POINTS = "reward_points"
    #Potential-Dup

• "start_date":

  • CONF_START_DATE = "start_date"
  • ATTR_START_DATE = "start_date"
    #Potential-Dup

• "end_date":

  • CONF_END_DATE = "end_date"
  • ATTR_END_DATE = "end_date"
    #Potential-Dup

• "criteria":

  • ATTR_CRITERIA = "criteria"
  • DATA_CRITERIA = "criteria"
    #Potential-Dup

• "custom_interval":

  • CONF_CUSTOM_INTERVAL = "custom_interval"
  • DATA_CUSTOM_INTERVAL = "custom_interval"
    #Potential-Dup

• "custom_interval_unit":

  • CONF_CUSTOM_INTERVAL_UNIT = "custom_interval_unit"
  • DATA_CUSTOM_INTERVAL_UNIT = "custom_interval_unit"
    #Potential-Dup

[ad-ha]

Thanks for the comment and for having a look into this.

Initially I was going to merge a lot of consts and try to get them reduced, but looking into your comment before about the categories and division, I thought that maybe it would be worth and more future-proof (if there are changes that may needed) to break these by groups. Not that it matters much, but since I am pretty much going line by line, to separate input from data (to merge after to coordinator), it doesn't hurt much doing the breakdown now, as it will be easier that making these in the future if needed. And also the new import method makes it way easier to manage different consts (even if duplicated), rather then having an infinite list on the import section of each file, so I am not so worried about it.

There are some consts that are going to be phased out, but I am not clear yet on how it will end, but that's the main reason why some are still there although not used.

I am being able to move this a bit faster that initially thought. The ones that will take more time are OptionsFlow and Coordinator (ConfigFlow is kinda of a copy of OptionsFlow, so will be easier once I finish).

I believe the best option is to get the above OptionsFlow and Coordinator finished, as these are key for almost every other file to get the DATA_X consts and other details. If you want, and have time, maybe having a look into structuring the const file would be nice, until I get the other files ready 👍

Cheers

[ad-ha]

Hi,

Finally I was able to get OptionsFlow finalized with the const revision. Also made a lot of progress on Coordinator data management structure as well, although a lot is still outstanding... 🙄

If you have time, you may check the files updated on 0.4.0 pull in dev.

Cheers

[ccpk1]

Sorry for the slow reply, I’ve been on Spring break this past week, so I haven’t been online. I’ll take a look on Monday when I’m back home

[ad-ha]

No worries. Hope you are enjoying some family time. 🌞

I have been doing a lot of progress on this and I believe I got it quite better now and handling way more situations.

Here some samples:

Whenever you get back and have time, give it a go.

I still need to check some other extra attributes on sensors and so on, but will get back into it during next week.

[ad-ha]

Hi,

I believe I got this quite rounded already and everything seems to be working smoothly.

@ccpk1 if you have the time to do a test drive as well to latest 0.4.0 PR, I will appreciate.

I am now just adding some cosmetic changes to the code, aligning LOGGER messages to make it all a bit more consistent.

Let me know if you are able to give it a ride and any outcomes. I would ideally look forward to release this week or next week, but would like feedback on your side as well, just in case I missed something (which most probably I may have, with all the changes done).

Cheers

[ccpk1]

I was able to spend a little time testing today, but only through some of the options flow testing related to constants. Found some issues I was able to address. Couple of notes:

• I'm working against the most updated dev instance that I synchronized a few hours ago, so I was surprised this is telling me it can't automatically be merged. Let me know if I'm doing something wrong, or if there is another branch I should be going against.
• Found a few duplicate constants, one with different value, so take a close look at how I handled those. As listed in the pull request, one set of the calendar attributes aren't used at the moment, I just renamed them until you decide how you want to handle.
• I noticed that you have deprecated the extra sensors we talked about in last release, but I don't see it listed specifically in any of the pull requests, so we'll want to be sure that gets listed as a breaking change.
• I see you had a pull request to add the general options of updating the coordinator interval as well as the point buttons, but I don't see that showing up in the dev instance.
• I started to look at badges, but I was getting quite a few errors right away, so I'm thinking that maybe not everything you're working on is synced up to dev yet.

Once I know for sure we're all working from the same version, I should be able to spend a little more time this week.

[ad-ha]

Hi @ccpk1

You would need to get the dev instance to update from this PR: #140

I believe it will be better to get the dev to update will all changes done up to now and get it based form both of us. I will push PR 140 through.

[ccpk1]

Got it. I didn't realize I could do that, so I'm sure that's why it isn't working as I expected. I'll try that out a little later. Thanks!

[ad-ha]

I believe it will be better to get the dev to update will all changes done up to now and get it based form both of us. I will push PR 140 through.

I was going to merge the whole #140, but it will go directly into main, so cannot do it. You will need to get your instance to update dev with the current commits. You should see PR #140 like this:

You just need to pull the changes and you should get a similar code to the actual dev branch. It might be worthy to compare the code you get on VS Code with this: https://github.com/ad-ha/kidschores-ha/tree/dev/custom_components/kidschores

[ccpk1]

Always learning something new here... 😄 Got that working using the pull request and started to poke around. Overall working much better now. I found one issue I logged, but will spend some more time tomorrow testing things out.

I also updated my dev dashboard branch with the fixes to handle the new points buttons that have entity names with _0 for float. Only handles a single decimal now, but I'm guessing that should be OK.

[ccpk1]

Spending a little more time looking through all the changes, it is really coming together nicely! You've put a lot of effort into improvements here!

As I was doing some testing, I realized there’s quite a bit of duplication between config_flow and options_flow, and both need to be maintained, as well as tested independently. I also noticed some functional differences too — for example, badges only allow cumulative mode in config_flow, which isn’t consistent with options_flow. (I generally understand why that is)

To help reduce this complexity, I’d like to propose two possible approaches:

Option 1 – Minimal Initial Setup
Use the config flow to create just the base config entry (or maybe just points, kids, and parents), then display a message directing users to complete setup through the integration configuration. This greatly reduces code maintenance, especially since most users will only run config once.

Option 2 – Reusable Flow Helpers for create/add
Move the bulk of logic (add_user, add_parent, add_chore, etc.) into centralized flow_helpers. 80-90% of the code to add each item is the same. Only slight variation in approach to setup multiple at once in the config flow, which could be handled in a centralized helper method which would allow reuse across both config and options flows. For example create a helper called _prepare_badge_data that would process all the user inputs and eliminate most of the duplication between the two

Personally, I lean toward Option 1 for its simplicity and lower long-term maintenance burden. Also, I'm sure you would have much preferred that I bring this option up before you did all the refactoring for constants, but regardless, it could still further simplify things for the future changes. Let me know what you think.

[ad-ha]

Hi,

Thanks for the checks and notes. Let me try to clarify some of this:

I realized there’s quite a bit of duplication between config_flow and options_flow, and both need to be maintained, as well as tested independently.

True. This is on my bucket list, but to ease the release I just preferred to leave this aside by the moment. They share the same schemas, so it's quite easy to manage afterwards.

I also noticed some functional differences too — for example, badges only allow cumulative mode in config_flow, which isn’t consistent with options_flow. (I generally understand why that is)

During ConfigFlow the user still does not have all things prepared and ready to set all types of Badges, nor they may have a clear idea of the capabilities of each.. so I preferred to leave only "Cumulative Badges" as the core for Badges and every other complementary badge is added/managed from OptionsFlow.

I also lean towards Option 1, that why "Cumulative Badges" are on ConfigFlow, like the minimum to get started. I believe the actual setup during ConfigFlow it's quite easy to follow and easy for any user to get the minimum requirements for the integration set, even for testing purposes.

While I cannot redirect users to OptionsFlow from ConfigFlow, since the integration is not yet loaded, I may add a message to the summary. I will have a look and check.

Right now, the balance between ConfigFlow and OptionsFlow for me seems quite good, aside from merging both add steps from OptionsFlow and ConfigFlow to have less code to maintain.

[ccpk1]

I'm fine either way, but figured I would mention some alternatives to simplify. This way it is at least a conscious decision to maintain the additional, even though it doesn't get a lot of use, except initial setup.

[ccpk1]

Do you want me to add issues in this thread or log them as actual issues for the 0.4.0? For now I will list this next one here. It's taking me a little while to understand all that you're doing with badges, but I'm getting there...

1. Recommend that badge sensor state is always threshold. If there is no threshold, then default the state to zero. Mixing with points doesn't add value in my opinion since it won't be consistent. Better to just get points from an attribute if applicable for that badge.
2. I'm starting with a detail review on cumulative badge before moving on to other types. See the screenshot below where the none award mode doesn't allow submitting due to validations that shouldn't be required.
3. The logic to clear out the points and other unnecessary input fields on submit isn't working. (Update - this is working on cumulative, I saw the issue on special badges, which I'll come back to later.)
   

More later...

[ad-ha]

Thanks, I was sure I would leave something behind and miss.

You may post the issues here, no problem. Although, for tracking purposes, if you prefer, you may add issues on the Git with a [DEV] tag, to differentiate.

About your remarks:

1. Recommend that badge sensor state is always threshold. If there is no threshold, then default the state to zero. Mixing with points doesn't add value in my opinion since it won't be consistent.

This is differentiated based on the sensor type, but it might make sense to get the threshold only and carry the pints into an extra attribute.

2. he none award mode doesn't allow submitting due to validations that shouldn't be required.

Nice catch. I've added the None at the end and may have missed to update the conditional checks.

3. The logic to clear out the points and other unnecessary input fields on submit isn't working. (Update - this is working on cumulative, I saw the issue on special badges, which I'll come back to later.)

I believe I tested everything and seemed to be working. Anyhow, if you find the issue again, let me know and I will have a better look into it.

Cheers

[ad-ha]

The value error on Award Reward shall be fixed. On cumulative I was missing to add the Empty reward option.

Let me know if it works now.

Tomorrow I will have a look into the reset dates.

Cheers

[ccpk1]

FYI - I"m working through a number of changes on the options flow for the various badge types that I"ll submit later. Just didn't want you to duplicate any effort.

[ad-ha]

Alright, thanks for the heads-up. Today I have been tide to work matters and could not have a look into.

Cheers

[ccpk1]

Couple of questions on badges before I can wrap up these option flow changes.

Special Occasion badge - Is the "Recurrent" option supposed to be there, and if so, how is it intended to be used since there are no schedule options?

Periodic Badge - This one looks to have really good potential

1. Similar to above question, how is the "Recurrent" option intended to be used since there are no schedule options except the reset? Or in this case does it somehow work with the custom dates?
2. Might be the same as number 1, but if I set a custom schedule, would that be just a one time reset?
3. Are the Points/Chores calculated just during that period? If so, where is the value stored?
4. Is selecting a chore optional?
5. If I do select a chore or multiple chores, are the Points/Chores only calculated based on completions of those specific chores.

[ad-ha]

Sure thing. Here is what I implemented and my thoughts:

0. Special Occasion Badge: The recurrent will reschedule the event for next year. The recurrency is 1-year basis.
1. On Periodic Badge, the recurrency is defined by the start and end periods. Once it gets to the end date, it will restart on the next day for a similar interval of time.
2. Same as question 1.
3. For periodic badge, yes, the points are calculated separately. It is based on the points baseline at the start date.
4. Yes, chores are optional. You can either define only some chores to the count or all chores (none selected).
5. Yes. If those chores are completed, they will count towards the threshold. Any other chore will not be included on the calculations... unless I missed something along the code on coordinator's function that handles now all badge calculations.

Cheers

[ccpk1]

Thanks, digging in deeper is leading me to more questions...

Cumulative badges:

1. Custom Reset Date - It looks like that is a one time reset option or is there a function that will reschedule it annually or otherwise?
2. Looking at the _process_cumulative_badge_reset, I don't think the current logic will properly support more than one cumulative badge. Maybe I'm missing it, but "cumulative_badge_baseline": 0 and "cumulative_earned_points": 0 are stored per kid, not per kid per badge. I think this needs to be changed so that the tracking will occur for each badge and each kid? Or track the baseline and earned points for each kid with each badge?

[ad-ha]

Again, with everything redone, I may missed things. I am with a lot of work right now and have been doing this in some free time, so not really going through it the whole time and between jumps something got lost in the way.

About the comments:

1. It is a one time reset, like airlines miles. When you get to the end of the year and have to earn X points before being downgraded to the level before the one you have. My reasoning was similar, thus the grace period and the maintenance rules. The idea is that it will reset on that date... although I may have missed the reschedule for custom dates.
2. Right. I missed that. Just revised the data and thought I added a chore ID to the marker. Will have a look and revise tomorrow as this really needs to be by kid and badge. Nice catch.

[ad-ha]

2. Looking at the _process_cumulative_badge_reset, I don't think the current logic will properly support more than one cumulative badge. Maybe I'm missing it, but "cumulative_badge_baseline": 0 and "cumulative_earned_points": 0 are stored per kid, not per kid per badge. I think this needs to be changed so that the tracking will occur for each badge and each kid? Or track the baseline and earned points for each kid with each badge?

I replied to this quite fast yesterday and was quite tired. So, cumulative badges are only tracked one by one, as it goes by levels. That's why it only tracks one and the baseline is just for one. It is the initial idea of, for example, Silver, Gold and so on that we had on samples.

The idea is that if a kid is currently at Gold, we will check if they keep that "status" or downgrade to "Silver". So on cumulaitve the tracking is just for their current cumulaitve ("level") badge.

Hope this clarifies and makes sense. At least to me it makes sense and seems ok.

Let me know your thoughts any how.

[ad-ha]

Adding to this:

On the reset period I changed the current Custom option to "Custom: 1-Year" and "Custom: 1-Month". If any of those options are selected, the date will bump for the period defined (1-year ot 1-month) on the reset date, rescheduling it again for future use.

Have a look and see if it all makes more sense now.

Thanks

[ccpk1]

The tracking of points for the cumulative in a single field makes sense to me now, thanks for explaining your logic.

Coming back to the custom options for cumulative. Just to confirm, there is no longer a one time custom reset option, it is always recurring, either every month or every year on the custom date selected? (I think it makes sense, just confirming it is what you intended.)

[ad-ha]

Glad it helped.

Yes, if it resets makes sense to make it every period, not just once, I guess. Either reset periodically or no reset at all. Right?

[ccpk1]

Now a bit more on Periodic Badges. I don't think they are working exactly as you listed above.:

1. Point Tracking does not seem to be limited to only selected chores. It's using the kid weekly and monthly sensors which would not be limited
2. If badge is set to chore count, but no chores are selected, the periodic_badge_success item increases every time the _check_badges_for_kid runs, even if they didn't do any chores. (i.e. just updating points for a kid will cause this to run and increment, so I assume it is an issue even if chores were selected, so this one probably needs rethought.)
3. It looks like when using chore count, it is tracking the number of successful times all chores are completed, not really the count of chores completed.
4. Is it correct that the "Recurrent" option only applies if you are using a custom schedule? Otherwise the schedule has to be set and the only options are weekly, monthly or custom. I think it's fine, just want to ensure I'm understanding how it is used. (It's a little confusing because, for instance, the schedule is weekly, but recurrent is turned off. ) I'm thinking about forcing it to always be on, but then possibly allow it to be turned off if custom is selected, then it could also be used as a one time badge.
5. I don't see anywhere that this badge would be removed. So if it's a periodic badge, does it make sense that once I receive the badge, I keep it forever?

[ad-ha]

On these comments:

1. Let me have a look tomorrow, if I get sometime, but I believe I was only checking on those. Unless I got that change out as I had an issue last week that I lost some changes and may have missed to redo that check.
2. I have been looking for the best place to do that call as I as getting a similar output on the place I made the call initially. After the change it seemed to work fine, but will have a look... if not I will get a new placement or change the logic to avoid that.
3. Will recheck.
4. So the recurrency is to be set when you want this to be reschedule and run "forever". If you want a one of, you may set the schedule without having the badge to reschedule and it will stop being checked.
5. Yes. The whole idea is all badges are kept forever, even if the badge is deleted. On a once earned, it will be kept. The only badges that can be "lost" are cumulative to work more as "levels".

Hope this helps. I am quite tired today to keep going through this, but will try to get a moment tomorrow to sort some of these issues.

Thanks a lot for the reviews! Appreciate 👍

[ad-ha]

Hi,

I made some changes on this.

• Added new periodic badge tracking per badge, when chores are defined. New keys are tracker per kid and badge, only summing when chores required are approved.

[ccpk1]

I just submitted a pull will a list of changes that should get the config and options flow pretty well cleaned up for badges. There may still be some small adjustments depending on the outcome of the questions above. I'll take a closer look at all of your responses tomorrow, but thanks for providing.

I mentioned in the pull request too, but there are a couple of comments I listed that you should take a look at within the code. They are noted with "#### **** CLS"

No rush on my side, get some rest and let me know if you have questions about anything I sent over.

[ad-ha]

Thanks a lot.

Let me see if I can spare sometime today and have a look.

Cheers

[ccpk1]

I don't see where special occasion badges are removed. I understand for other badge types, but I think this type should be removed if the date does not match. Otherwise kids would have birthday and holiday badges every day of the year. Thoughts?

One other question... I think we should provide more instruction / hints on the CFOF forms. Specifically for things like the "Recurrent" toggle as it shows on the special occasion form. I know we can use the data_description in the translation files to add that when adding badges, which I was starting to do, but then realized that when choosing the edit_badge option that is all done in one function, so the same description is used for editing all forms. For instance it would be good to have a better description at the top of each form that could state that cumulative badge is points only or that recurrent button on the special occasion badge is for annual recurrence. Any thoughts on best way to handle?

[ad-ha]

So the whole idea for Special Badges is to award them and get them on "display", if you remove it will be like the kids did not earn them. Maybe I am not explaining myself well, but it is not lost.. Is like a medal that you get to keep.

Understood on the data. Maybe we will have to duplicate keys for each edit step, so after we can define the correct content for each trans_key on the reanslation files and data_description.

[ccpk1]

I do understand what you are saying about keeping badges. Makes perfect sense. I"m struggling with that concept for special occasion badges though. Take a look at the scenario below:

• I have no badges to start...
• My birthday comes along - I do a chore that day, so I get a Badge that says Happy Birthday that I see every day of the year in my badges
• Now Christmas comes along - I do a chore that day, so I get a badge that says Merry Christmas
• I now have these two badges "earned" / "assigned" to me all year long, every time I look at my badges. So in July, I still see I have the Christmas badge which seems odd to me.
• Next Christmas / Birthday comes along, and I already have the Christmas badge. I know it quickly gets removed and re-added if I do a chore, but even if I don't do any chores, but I still keep it.

This isn't a big deal to me one way or the other, I just don't think it is what people would generally expect, so want to make sure we consciously choose how to handle it.

[ad-ha]

Hey,

I understand your point, but maybe we just need to add a counter on Special Badges to show how many times they were earned.

I just thought now about HA Community badges, which have a similar behavior.

[ccpk1]

Thanks for the example, that helps. I'm fine with leaving them in place, we can see what the feedback is as others start to use it.

That said, with all the extra focus on badges, I'm sure there are going to more requests to delete earned badges because they don't want them anymore, or accidently put the wrong threshold in, etc. I went ahead and created a service that will allow easy removal of any or all badges from kids, so that should help with any special handling requests we get. Take a close look at how I'm clearing the extra fields per badge type, but specifically for cumulative, to ensure you're aligned. Easy to adjust if needed.

LMK if you have any thoughts or questions.

[ad-ha]

Hi,

Glad it did help to clear a bit more my idea 😄

Just looked into the service and seems alright. I agree it will be better to have a way to handle those removals if the users want to, so fine for me. Thanks.

[ccpk1]

I just created a pull request you've probably already seen, so I won't duplicate the details here, but there are a few things to decide on as a result.

1. New badges_earned field for kids is setup and working, but also left the existing "badges" field in place and ensured both are working. Since this new field is more full featured, we could choose to remove the current simple "badges" list field, or it would also be pretty easy to just implement the badges_earned logic for the existing badges field. I don't have a strong preference here, but of course changing the existing badges field might cause some breaking changes for those that don't use the dashboard or don't update to the newest dashboard.
2. Cumulative badges were excluded from award processing and only updated the multiplier. I assume that was just an oversight and the awards listed in cumulative should be awarded when the badge is earned? Please confirm.
3. I believe special occasion badges and cumulative (non-reset) badges are working pretty well now. Overall logic was solid, but there were a number of little things and scenarios I found that needed tweaked. That said, I was just starting to look at the reset schedule and recurring schedule:

--a. When a reset date occurs for cumulative, should the awards be processed again? i.e. if the badge has a 50 award points listed, should that be given upon every reset?
--b. For periodic badges and daily badges, should the awards be processed on every reset?

4. Right now, it looks like the _check_badges method only processes badges that have not been earned, other than special occasion. I see some of the logic for handling reset and reschedule further down in that method, but I don't think it will ever get called after the badge is awarded. I assume this is just an open item that needs worked on?

Open Items -
Migration code to sync up badges_earned with existing badges - Once we agree on the first question, this can be added.
Add a few attributes to sensors for use in dashboard updates
Test and confirm daily, periodic badges as well as badge reset processes
Test and confirm achievement and challenge linked badges.

[ad-ha]

Hey,

I was tied this weekend with a lot of kids agenda, so did not have a lot of time to go through this. Let me try to address some of your concerns and we can agree on a developing path for this:

1. Maybe it will be better to directly migrate the current badges into the badges_earned dict. If we create a migration function, this would not create any major breaking change and we could have everyone on the same page. I did not revise your new code entirely yet, but I figure this would be the best course of action. Get everything migrated into the same place and all the new logic handling everything together. Do you agree?
2. That was a mistake on my end. Initially I did not think of adding awards to the cumulative badges, but after it did make sense and forgot to update the logic on that. So, yes, they should be part of the awarding logic.
3. This is quite a tricky one to sort, but let's see if we can make up something that makes some sense:
   a. For all badges, I believe, if an award is set and there is a reset period assigned, the kid should obtain the awards again. At the end of the day, if they achieve the badge, they also deserve the awards.
   b. Same here. If after the reset they get the award, I believe the awards are implicit.
4. I could easily be missing things. I did not have a lot of time to test it all (especially resets) and got along with the code as fast as I could, as this week I would not be able to do much. Anyhow, I will try to revise it as well and have a better look.

On the open questions:

1. Yes, I believe the migration would be the best approach.
2. Seems good. Once if finalize the core of the code we can define those new attributes.
3. and 4. Seems ok to me.

Thanks a lot for your work on this. Really appreciate! 👍

Cheers 🍻

[ccpk1]

1. I agree, let's just migrate to badges_earned and deprecate "badges" field
2. Agree, that is how I have them set now
3. Agree, the award should happen at every successful reset. That also makes the most sense in the case of demoting because they will miss the award for that period and move to the lower multiplier as penalty. Additionally, we will increment the number of times the badge was awarded and last awarded at each successful period end.

Thanks!

[ccpk1]

@ad-ha - I'm guessing you've had a busy week since it's been quiet here. I have some pretty significant updates coming later tonight or tomorrow, so just wanted to let you know it might be good to hold off doing anything until I get all these changes integrated in. (I touched a lot of core pieces doing cleanup primarily related date / time scheduling as well as of course badges. Also, don't spend any time trying to answer my questions from the other day on badges, I think I've come up with good solutions to most of them.

[ad-ha]

Hi @ccpk1 ,

Thanks for the update. Yes, this week has not been easy and I did not get any free time to look into this. Sorry.

Great to know you were able to make progress, I am sure it will come out great.

I thought I answered all outstanding questions, but maybe I missed something, although II was quite sure to comment on everything. Anyhow, glad you found a way on it.

Cheers

[ccpk1]

I'm putting the required items to get to the next release in the issues list with a tag of [DEV].

That said, there are some things I've been noting down as I worked through all the changes over the past few weeks. The items below are my top 5 enhancements I'd like to see. They aren't in any particular order, and none of them are critical to get done before the next release, but I also don't want to lose track of them. A lot of the logic and functions I built in recent updates were done in a "common" way that would allow re-use in many of the enhancements below. Let me know if there are any in particular that you would want to push for prior to the next release, otherwise we can copy them into requests if they are longer term.

1. Badge Award Enhancements (Complete)
2. Reward claims, approvals and possible fulfillment
3. Individualized Chore Handling with Per-Kid Chore Data
4. Rework Achievements and Challenges Using Badge Logic and Infrastructure
5. Centralized Notification Handling

1. High-Level Plan: Unified Badge Award/Penalty Multi-Select

1. Configuration/UI Changes

• Remove the award_mode field - This can be determined by the values in the new award_items field and the award_points field.
• Replace the award_reward dropdown with a single multi-select field, e.g. award_items.
• The dropdown is dynamically populated with all available rewards, bonuses, and penalties.
• Each option is labeled by type, e.g.:
  • REWARD: Ice Cream
  • BONUS: Big Helper
  • PENALTY: Missed Chore
• The value for each option can be a composite key, e.g. reward:ice_cream, bonus:big_helper, penalty:missed_chore.

2. Backend Logic

• When a badge is awarded:
  • If award_points > 0, award those points.
  • For each selected item in award_items:
    • If it’s a reward, grant the reward.
    • If it’s a bonus, grant the bonus.
• When a badge is expired or not re-awarded on reset:
  • For each selected PENALTY: item in award_items, apply the penalty.

3. Dynamic Option Generation

• The dropdown options are generated at runtime from the current lists of rewards, bonuses, and penalties.
• Ensure labels are clear and unique.

4. Migration

• Migrate existing badges to the new award_items list, preserving their current reward/bonus/penalty selections.

5. Documentation & UX

• Update documentation to explain the new unified field and selection process.
• In the UI, ensure the dropdown is multi-select and clearly labeled.

6. Summary

• One field, many types: flexible, future-proof, and user-friendly.
• Logic is type-aware and context-sensitive (award vs. penalty).

---

2. Reward claims, approvals and possible fulfillment

Currently, reward claims are reset at midnight. This means:

• If a parent does not approve a reward claim before midnight, the claim disappears.
• Parents may miss or lose track of reward claims, especially if they are not able to fulfill them immediately.
• There is no explicit tracking of whether a reward has actually been fulfilled (physically given to the child), only that it was approved in the system.
• Additionally, the current award process can automatically add approved rewards, which still does not solve the problem of tracking fulfillment or ensuring parents are aware of all pending rewards.

This can lead to confusion and unfulfilled rewards, reducing trust in the system for both parents and kids.

---

Proposal

Short-Term Solution

Remove the midnight reset on reward claims.

• Allow reward claims to persist until they are explicitly approved or disapproved by a parent.
• This gives parents flexibility to approve claims when they are able to fulfill them, without worrying about missing the midnight deadline.
• Note: This still does not handle the scenario where the award process automatically adds approved rewards, which can make it hard for parents to track what needs to be fulfilled.

Long-Term Solution

Improve reward claim and fulfillment tracking.

Options:

1. Add explicit fulfillment tracking for rewards:

   • Add a new state or flag for each reward claim: claimed, approved, fulfilled.
     • claimed: The kid has requested the reward.
     • approved: The parent has approved the claim (points deducted, etc).
     • fulfilled: The parent has marked the reward as physically given to the child.
   • Update the UI to show the status of each reward claim, and allow parents to mark rewards as fulfilled.
   • Optionally, add notifications or reminders for unfulfilled approved rewards.
   • Keep a history/log of all reward claims, approvals, and fulfillments for transparency.

2. Alternative: Enhance claim process with metadata (without adding a fulfilled state):

   • Continue using only claimed and approved states.
   • When a reward is claimed (either by the kid or automatically as part of an award), capture and store:
     • The date/time of the claim.
     • The source of the claim (manual, award, etc).
     • The cost (zero for an award, or the actual cost for a manual claim).
   • This way, both the kid and parent can see all pending and approved rewards, know when and how they were claimed, and whether there was an associated cost.
   • Approval of the claim can be done at any time, and all claims remain visible until acted upon.

---

Benefits

• Short-term: Parents have more time and flexibility to approve claims, reducing missed or lost rewards.
• Long-term: The system becomes more robust and trustworthy, ensuring that rewards are not just approved in the app, but actually delivered to the child, or at least clearly tracked with all relevant details.

---

3. Proposal: Individualized Chore Handling with Per-Kid Chore Data

Issue/Background

Currently, chores assigned to multiple kids share state and due dates, which is not intuitive. Each kid should have their own independent progress and deadlines for the same chore. The groundwork for this is already in place with the chore_data structure under each kid.

The idea to handle chores this way was inspired by the process used to build the badge system, which required individualized schedules and state management for each kid. The badge system demonstrated the benefits and flexibility of per-kid data handling, and made it clear that a similar approach would be ideal for chores as well.

Importantly, chore_data was intentionally designed with this future direction in mind, anticipating that individualized chore handling would likely become necessary as the system evolved.

---

Plan

• Chore Configuration:
  The global chore object remains as a template/configuration, holding the default schedule, name, description, and any shared settings.

• Per-Kid Chore Data:
  All processing, state, due dates, and rescheduling logic moves to the chore_data under each kid.

  • Each kid’s chore_data entry tracks their own state, due date, and schedule for each assigned chore.
  • State transitions (claimed, approved, overdue, etc.) and reschedules are handled per kid, not globally.
  • Overdue handling and rescheduling only affect the individual kid’s instance of the chore.

• Shared Chores:
  The global chore object could optionally be used to hold data for truly shared chores, but for most cases, all state and due date management would be independent per kid.

• Default Schedule:
  The default schedule is still defined at the config/global chore level. When a chore is assigned to a kid, the default schedule is copied to their chore_data. Any rescheduling or overdue handling after assignment is managed individually.

• UI/UX:
  The UI should reflect each kid’s unique progress and deadlines for their assigned chores, even if the chore is the same for multiple kids.

---

Benefits

• Chores assigned to multiple kids are now truly independent in state and due date.
• Matches user expectations—each kid’s chores are tracked separately, even if the chore is the same.
• Shared chores can still be supported if needed, but the default is individualized handling.
• Aligns with the badge system, which already uses individualized scheduling and state.
• Leverages the original design of chore_data, which was built with this future in mind.

---

Implementation Notes

• Refactor processing code to always reference and update the per-kid chore_data for state and due date.
• Use the global chore as a template only; never store state or due date there except for shared chores if needed.
• Migrate any remaining global state/due date data to the per-kid structure.
• Default schedule is only used at assignment; all further scheduling is per-kid.

---

4. Proposal: Rework Achievements and Challenges Using Badge Infrastructure

Background

The badge system was designed with flexible, individualized scheduling, target tracking, and progress monitoring. Many of the requirements for achievements and challenges overlap with what has already been implemented for badges, such as:

• Target/goal tracking
• Awarding components (points, rewards, etc.)
• Reset schedules and progress monitoring
• Per-kid state and progress

---

Proposal

Leverage and extend the badge system’s infrastructure and helper functions to enhance achievements and challenges.

Key Points

• Unified Target Tracking:
  Reuse the target monitoring and progress logic from badges for achievements and challenges. This reduces code duplication and ensures consistent behavior for all progress-based features.

• Flexible Awarding:
  Use the same award component logic as badges, allowing achievements and challenges to grant points, rewards, bonuses, or penalties using the new unified award system.

• Reset Schedules:
  Achievements and challenges can use the same reset and progress monitoring logic as badges, making it easier to manage recurring or time-limited goals.

• Dependency and Progress Criteria:

  • Achievements and challenges can now use badge progress as criteria.
  • For example, an achievement could require earning a specific badge, or reaching a certain level of progress on a badge (e.g., "Earn the 'Super Helper' badge 3 times").
  • Challenges could also be set up to require or measure badge progress among multiple kids, enabling new types of competitive or cooperative goals.

• Enhanced Challenge Capabilities:
  For challenges assigned to multiple kids, extend the infrastructure to support true competition:

  • Track and compare progress for all assigned kids.
  • Optionally, award prizes or recognition to the winner(s).
  • Support both cooperative and competitive challenge types.

• Simplified Management:
  By reusing badge helper functions and data structures, configuration and management of achievements and challenges becomes more consistent and less error-prone.

---

Benefits

• Consistency: All progress-based features (badges, achievements, challenges) share a common foundation.
• Extensibility: New types of targets, dependencies, and awards can be added in one place and used everywhere.
• Badge Progress as Criteria: Achievements and challenges can now directly measure badge progress, enabling more complex and meaningful goals.
• Competition Support: Challenges can now support real competition between kids, with clear tracking and fair measurement.
• Reduced Maintenance: Less duplicated code and logic, easier to test and extend.

---

Implementation Notes

• Refactor achievements and challenges to use badge-style per-kid data and progress tracking.
• Expose badge progress and state as possible targets for achievements and challenges.
• Allow configuration of achievements/challenges that depend on earning or progressing specific badges.
• Update UI to reflect new capabilities and dependencies.
• Migrate existing achievements and challenges to the new structure.

---

5. Proposal: Centralized Notification Handling

Problem

Notification logic is currently scattered throughout the codebase, with direct calls and custom formatting in many places. This leads to duplicated code, inconsistent messages, and makes it harder to update or extend notification behavior.

---

High-Level Solution

• Central Notification Function:
  Implement a single, centralized function (or class) responsible for sending all notifications (to kids, parents, or both). All notification requests should go through this function.

• Notification Templates:
  Define and maintain notification templates in one place. Each template should cover the title, message, and any actions for common events (e.g., chore claimed, reward approved, badge earned). Templates should support translation and dynamic placeholders.

• Consistent Processing:
  The central function handles:

  • Selecting the correct template based on event type.
  • Filling in placeholders with relevant data.
  • Choosing the appropriate delivery method (mobile, persistent, etc.) based on user preferences.
  • Logging and error handling.

• Benefits:

  • Consistent, professional notifications across the system.
  • Easy to update notification content or add new types.
  • Less code duplication and easier maintenance.
  • Simplifies future enhancements (e.g., new notification channels, batching, or throttling).

---

Summary:
Move all notification logic to a single, maintainable location using templates, and route all notification events through a central handler for consistency and ease of management.