Feature Request | Auto-assign categories based on bill title mappings

[AkshayRao27]

Context

In my ongoing quest to get Cospend to be a full-fledged Splitwise replacement for my friends and me, I realised that I do indeed miss the Auto-Categorisation feature that it had. Basically, as soon as you entered a bill title (e.g.. Aldi), Splitwise would update the category icon (e.g.. Groceries, in this case). It was FAR from perfect, often suggested wrong categories, often didn't suggest categories that it should have suggested, and there was no way to control its behaviour as a user.

Idea

When a bill is created without a category, Cospend should automatically assign one based on configurable Bill Title → Category mappings.

Database

A new DB Table will need to be created for this feature e.g. oc_cospend_auto_category_mappings

• The table has a category_id column that points to entries in oc_cospend_categories

Cospend Settings Menu

• A new "Auto-Categorisation" Menu
  • A toggle to enable/disable auto-categorisation (on by default): when disabled, all auto-categorisation-related elements (mapping table, checkboxes, prompts, buttons, etc) are hidden.
• A manual "Auto-categorise all existing uncategorised bills" button in settings which auto-categorises all bills with the category none in all projects that
  • do not have the "Enable Auto-categorisation of bills" toggled off and
  • are not archived.

Project Settings Menu (Categories)

• An "Enable Auto-categorisation of bills" toggle (on by default).
• A manual "Auto-categorise all existing uncategorised bills in this project" button which auto-categorises all bills with the category none.
  • This button is hidden if the "Enable Auto-categorisation of bills" toggle is off.
• A category mappings table showing Bill Title → Category.
  • The Title and Category columns can be sorted:
    • Alphabetically (A to Z and Z to A)
    • By creation date (if at all possible)
  • A button to add a mapping row.
  • Each table row has these options:
    • Edit Mapping.
    • Delete Mapping.
    • Copy mapping to Project(s): Clicking it reveals a multi-select picker of other projects where the user is a Maintainer/Admin and a submit button.
      • For each target project, it finds categories with the same name as the source mapping's category and creates the mapping there.
      • If a matching category name doesn't exist in a target project, that mapping is skipped and the user is warned.
      • After copying, the user is shown a summary e.g. "3 mappings imported, 1 skipped (mapping already exists for [title]".
  • If a duplicate Title → Category mapping is entered, the user gets a prompt saying that the mapping already exists.
  • If a mapped category is deleted, the mapping is shown in settings with an "invalid" warning and skipped during auto-categorisation until the mapping is updated with an existing Category.
    • Can potentially set category_id to null on category deletion
  • A "Copy all mappings to other projects" Button: Clicking it reveals a multi-select picker of other projects where the user is a Maintainer/Admin and a submit button.
    • For each target project, it finds categories with the same name as the source mapping's category and creates the mapping there.
    • If a matching category name doesn't exist in a target project, that mapping is skipped and the user is warned.
    • After copying, the user is shown a summary e.g. "3 mappings imported, 1 skipped (mapping already exists for [title]".
  • An "Import mappings from project" which pulls another project's mapping set into the current project. Clicking it reveals a drop-down list with a list of other projects where the user is a Maintainer/Admin and a submit button.
    • If a matching category name doesn't exist in the project, that mapping is skipped and the user is warned.
    • If the target project already has a mapping for a title, that mapping is skipped and the user is warned.

Auto-categorisation logic

• Auto-categorisation triggers for bills in a project if
  • It is switched on globally and
  • It is not deactivated inside the project.
• Matching is case-insensitive, exact title match.

Bill creation

• Cospend (web) automatically assigns a category to the bill once the user enters a bill title.
  • The categorisation triggers once the user leaves the title field.
• If the user manually changes the bill category to "None" after Cospend (web) has automatically assigned a category to the bill, the bill remains uncategorised.
• If the user manually assigns / changes the bill category, an optional checkbox / switch (unchecked / off by default) appears below the category drop-down with the text "Always assign [category] to bills titled [title]".
  • [title] and [category] always reflect the current [title] and [category], and not the ones from when the checkbox appeared (in case the user updates either of those values after the checkbox has already appeared).
  • The checkbox only appears if the bill already has a title (this prevents the checkbox appearing with an empty [title] placeholder in the text if the user enters a category before entering a title for whatever reason).
  • When activated, a new entry is created in the mapping table once the bill is saved.
  • If a category mapping already exists for bill title, the checkbox shows the existing mapping instead and asks the user whether to update it. If the user opts to update the mapping, the entry in the mapping table is updated once the bill is saved.
• When a bill is created without a category via the API (such as via MoneyBuster), a bill-category is automatically assigned server-side.
  • This will, of course, result in not being able to opt-out of auto-categorisation when creating bills from apps like MoneyBuster!
  • Potential workaround: add an API parameter like auto_categorise=false so that there's a way for app-created-bills to opt out of auto-categorisation?

Bill editing

• Like with bill creation, auto-categorisation only triggers
  • when the user leaves the title field.
  • if the title field goes from blank to not blank.
    • This will, of course, mean that if a user creates a bill via an App and edits it on web before the auto-categorisation has kicked in, auto-categorisation will not trigger because the bill title wasn't blank, and the user would need to either manually categorise the bill or use an "Auto-categorise all" button!
• Like with bill creation, if the user manually assigns / changes the bill category, an optional checkbox / switch (unchecked / off by default) appears below the category drop-down with the text "Always assign [category] to bills titled [title]".
  • The checkbox only appears if the bill already has a title (probably doesn't matter here, but still).
  • When activated, a new entry is created in the mapping table once the bill is saved.
  • If a category mapping already exists for bill title, the checkbox shows the existing mapping instead and asks the user whether to update it. If the user opts to update the mapping, the entry in the mapping table is updated once the bill is saved.

Permissions

• Auto-categorisation controls can be managed only by Project Maintainers and Admins.
• Auto-categorisation checkboxes in the bill menu appear only for Project Maintainers and Admins.

Potential future expansion ideas

• More Title → Category Mapping logic options (e.g. regex, case sensitive, etc)?
• Import / Export Mappings to .csv?

[AkshayRao27]

Decided to take a crack at this myself last night and got a prototype up and running with OpenCode and DeepSeek. There's still a whole bunch of stuff that I need to fix, but it's a decent start, I guess ^^

Screencast_20260614_142729.webm