@lunch-money/preset-categories

Shared preset category definitions for Lunch Money. This package exports the types and data for onboarding preset categories and the Plaid taxonomy mappings used by the Lunch Money server to enable auto-categorization of transactions.

Keeping frontend and backend definitions in one place avoids duplication and ensures consistency.

Installation

npm install @lunch-money/preset-categories

Exports

CATEGORY_PRESETS

Preset category definitions as an ordered array, matching UI usage (e.g. onboarding dropdowns).

Includes three presets:

• Basic Essentials (No Category Groups) — flat list of common categories
• Detailed Categories — grouped categories with subcategories (Housing, Utilities, etc.)
• Needs/Wants/Savings — budget-framework groupings

PRESETS

Same preset definitions as CATEGORY_PRESETS, keyed by preset name for lookup:

PRESETS['Basic Essentials (No Category Groups)']
PRESETS['Detailed Categories']
PRESETS['Needs/Wants/Savings']

REQUIRED_CATEGORIES

Onboarding-required categories that are always included when allowed:

• Income — marked as income via metadata.is_income
• Payment, Transfer — excluded from budget and totals via metadata

DEFAULT_CATEGORY_MAPPING

Maps Lunch Money category names to Plaid personal_finance_category taxonomy entries. Used by the server to auto-categorize transactions when users choose a preset category group.

Each value is either:

• a single PlaidMappingEntry ({ primary, detailed }), or
• an array of entries (for categories spanning multiple Plaid primaries, e.g. Payment, Transfer or Rent, Mortgage)

When detailed is null, the mapping covers the entire primary category.

Types

TypeScript definitions are provided in index.d.ts:

| Type | Description | |------|-------------| | PresetCategory | A single category (or group) with optional emoji, subcategories, and metadata | | PresetCategoryGroup | A named preset containing an array of categories | | PlaidMappingEntry | A Plaid primary / detailed pair |

Usage

Clients (onboarding UI)

import {
  CATEGORY_PRESETS,
  REQUIRED_CATEGORIES,
  PresetCategory,
} from '@lunch-money/preset-categories'

Contributing

When updating this package:

1. Edit index.js for category data and mapping changes.
2. Update index.d.ts if export shapes or types change.

Category and mapping changes

If Lunch Money preset categories are renamed, added, or removed, update DEFAULT_CATEGORY_MAPPING accordingly:

• New category — add a corresponding Plaid mapping entry when auto-categorization should apply. Categories intentionally left unmapped (e.g. savings buckets) do not need an entry.
• Renamed category — update the mapping key to match the new plain category name (without emoji).
• Removed category — remove the corresponding mapping entry if it is no longer used.

Category names in DEFAULT_CATEGORY_MAPPING must match the plain name values used in CATEGORY_PRESETS, REQUIRED_CATEGORIES, and related preset subcategories — not display names with emoji prefixes.

When a category spans multiple Plaid primaries, use an array of PlaidMappingEntry objects (see Payment, Transfer and Rent, Mortgage for examples).

License

ISC