find-subscriptions 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '069716e44081191145ee5737091b013be74948f27e263e959c4fdb27b26da198'
-  data.tar.gz: b9a5581e027c13554712011b9f967aa504ec9c5ef5609fb172ca8bdc2abc97bf
+  metadata.gz: 11a3975380aece18b36723e9187c87a24aedcc775a2dd8a196cd165c6375ee41
+  data.tar.gz: 20e28d7a29bfeba088043b181814475202d1b4a678b7347838fe7312c024be32
 SHA512:
-  metadata.gz: 791c068bc914f3d7a5ae7ba06bf1f659f921aa9cc0a367ac2002f35ee52fe7182e47a7c84cd71ffa3f9fa0e7c0d9ed93f0ba995636becb1ad39a05484f81e7e6
-  data.tar.gz: c66594b54e5241d4660d0bd3d433581bfaf7fda6d16700b397caf39b193e73d74bf0db61bb7f16991a51fa47dfed4d49c7b56f5c0cf238087b2d58ea73634efd
+  metadata.gz: cbbb7b9f12188c6201795d7a28b2f02f21ef3125032cc1878b7c63eb97c0459bd37a1d6449d25c2fde3de990150c92343a4fb997c223594e39964bafaf2c80b4
+  data.tar.gz: a8a53c131e70abbb2018c7d0b8698b7d4fd07471229e06d2c631b584dd22cb5387a08380ec2e37c3cc6425b631fa82c3e59d2d31a686e0954e35b3057238ce83

data/README.md

@@ -6,10 +6,40 @@ Scans bank and credit card CSV exports to surface recurring charges — subscrip
 
 - Ruby 3.x
 
+## Installation
+
+```
+gem install find-subscriptions
+```
+
+Or clone the repo and run directly:
+
+```
+git clone https://github.com/jeffreybaird/find-subscriptions
+cd find-subscriptions
+bundle install
+./bin/find-subscriptions --files EXPORT.csv
+```
+
 ## Usage
 
 ```
-./bin/find-subscriptions --files EXPORT.csv [options]
+find-subscriptions --files EXPORT.csv [options]
+```
+
+Run with no arguments (or `--help`) to see the full help menu:
+
+```
+find-subscriptions
+find-subscriptions --help
+```
+
+Get detailed help for a specific flag:
+
+```
+find-subscriptions --sort --help
+find-subscriptions --format --help
+find-subscriptions --set-config --help
 ```
 
 ### Options
@@ -25,6 +55,7 @@ Scans bank and credit card CSV exports to surface recurring charges — subscrip
 | `--from DATE` | Only include transactions on or after DATE (`YYYY-MM-DD`) |
 | `--to DATE` | Only include transactions on or before DATE (`YYYY-MM-DD`) |
 | `--format FORMAT` | Output format: `text` (default), `json`, `csv` |
+| `--set-config PATH` | Register a config YAML file to use as defaults on future runs |
 
 ### Output formats
 
@@ -35,8 +66,8 @@ Scans bank and credit card CSV exports to surface recurring charges — subscrip
 | `csv` | CSV with header row — open in a spreadsheet or feed into other scripts |
 
 ```
-./bin/find-subscriptions --files export.csv --format json
-./bin/find-subscriptions --files export.csv --format csv > subscriptions.csv
+find-subscriptions --files export.csv --format json
+find-subscriptions --files export.csv --format csv > subscriptions.csv
 ```
 
 ### Sort orders
@@ -67,29 +98,150 @@ Subscriptions whose last transaction is older than the duration are hidden. Usef
 Scan a single Amex export, auto-detecting the schema:
 
 ```
-./bin/find-subscriptions --files Amex-2025.csv
+find-subscriptions --files Amex-2025.csv
 ```
 
 Scan multiple files and force a schema:
 
 ```
-./bin/find-subscriptions --files jan.csv,feb.csv --schema american_express
+find-subscriptions --files jan.csv,feb.csv --schema american_express
 ```
 
 Filter out known/expected subscriptions and show only recent ones:
 
 ```
-./bin/find-subscriptions --files Amex-2025.csv \
+find-subscriptions --files Amex-2025.csv \
   --known-payees data/known_payees.yml \
   --inactive-for 6months \
   --sort last_desc
 ```
 
-## Supported schemas
+## Config file
+
+Save your preferred defaults so you don't have to repeat flags every run.
+
+**1. Create a YAML config file:**
+
+```yaml
+# ~/.find-subscriptions.yml
+sort: last_desc
+format: text
+min_amount: "5.00"
+inactive_for: 6months
+filter_known_payees: true
+known_payees_path: ~/.config/find-subscriptions/known_payees.yml
+```
+
+**2. Register it:**
+
+```
+find-subscriptions --set-config ~/.find-subscriptions.yml
+```
+
+This writes the path to `~/.find-subscriptions-config-path`. On every subsequent run, options from that file are loaded as defaults before any CLI flags are applied.
+
+**Option precedence (lowest to highest):**
+
+```
+built-in defaults → config file → CLI flags
+```
+
+CLI flags always win. The config file fills in anything you don't pass on the command line.
+
+**Supported config keys:**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `sort` | string | Default sort order |
+| `format` | string | Default output format |
+| `min_amount` | string | Minimum recurring amount to show |
+| `inactive_for` | string | Hide subscriptions older than this duration |
+| `filter_known_payees` | boolean | Apply `known_payees_path` filter by default |
+| `known_payees_path` | path | Default known-payees YAML path |
+| `schema` | string | Default schema name |
+| `from_date` | string (`YYYY-MM-DD`) | Default `--from` date |
+| `to_date` | string (`YYYY-MM-DD`) | Default `--to` date |
+| `schemas` | mapping | User-defined CSV schemas (see below) |
+
+> `files` is intentionally not supported in the config — you must provide it on the command line each run.
+
+## User-defined schemas
+
+Define custom CSV schemas in your config file without writing any Ruby code. This lets you analyze exports from banks not built into the tool.
+
+Add a top-level `schemas:` key to your config YAML:
+
+```yaml
+schemas:
+  my_bank:
+    required_headers:
+      - Date
+      - Description
+      - Amount
+    amount_key: Amount
+    direction: negative_debit
+    date_column: Date
+    date_format: "%Y-%m-%d"
+    payee_column: Description
+```
+
+Then use it by name:
+
+```
+find-subscriptions --files my_bank_export.csv --schema my_bank
+```
+
+Or let it auto-detect (your schema is checked after the built-ins, so unique headers help):
+
+```
+find-subscriptions --files my_bank_export.csv
+```
+
+### Schema config keys
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `required_headers` | yes | Array of CSV column names that must be present |
+| `amount_key` | yes | Column name containing the transaction amount |
+| `direction` | yes | How to determine if a transaction is outgoing (see below) |
+| `date_column` | yes | Column name containing the transaction date |
+| `date_format` | yes | `strptime`-compatible format string (e.g. `%Y-%m-%d`, `%m/%d/%Y`) |
+| `payee_column` | yes | Column name containing the payee/description |
+| `indicator_column` | if `direction: indicator_column` | Column holding debit/credit labels |
+| `debit_value` | no | Value in `indicator_column` that means "debit" (default: `Debit`) |
+
+### Direction strategies
+
+| Strategy | When to use |
+|----------|-------------|
+| `negative_debit` | Outgoing charges are **negative** numbers (most generic bank CSVs) |
+| `positive_debit` | Outgoing charges are **positive** numbers (e.g. American Express) |
+| `indicator_column` | A separate column labels rows as `Debit` or `Credit` (e.g. Navy Federal) |
+
+**`indicator_column` example:**
+
+```yaml
+schemas:
+  regional_bank:
+    required_headers:
+      - Posted Date
+      - Description
+      - Amount
+      - Transaction Type
+    amount_key: Amount
+    direction: indicator_column
+    indicator_column: Transaction Type
+    debit_value: Debit
+    date_column: Posted Date
+    date_format: "%m/%d/%Y"
+    payee_column: Description
+```
+
+## Supported built-in schemas
 
 | Name | Bank / Issuer | Required CSV headers |
 |------|---------------|----------------------|
-| `american_express` | American Express | `Date`, `Description`, `Amount` |
+| `american_express` | American Express | `Date`, `Description`, `Amount`, `Card Member` |
 | `navy_federal` | Navy Federal Credit Union | `Transaction Date`, `Description`, `Amount`, `Credit Debit Indicator` |
 | `generic` | Generic (YYYY-MM-DD dates) | `Date`, `Description`, `Amount` |
 
@@ -117,7 +269,7 @@ Each entry requires:
 - `normalized` — internal deduplication key (lowercase, used for grouping)
 - `patterns` — list of Ruby regex literals in `/pattern/flags` format
 
-`data/known_payees.yml` is the default file and is always loaded for payee normalization (display names). Filtering only applies when `--known-payees` is explicitly passed.
+`data/known_payees.yml` is the default file and is always loaded for payee normalization (display names). Filtering only applies when `--known-payees` is explicitly passed (or `filter_known_payees: true` is set in the config).
 
 ## Output format
 
@@ -126,3 +278,7 @@ Subscriptions:
   - SPOTIFY                                                               : $9.99 since January 2025 (14 transactions) until February 2026
   - NETFLIX.COM                                                           : $15.49 since March 2024 (12 transactions) until February 2026
 ```
+
+## License
+
+PolyForm Noncommercial License 1.0.0 — free to use and fork for personal and open-source projects. Commercial use prohibited. See [LICENSE](LICENSE).

data/lib/find_subscriptions/cli.rb

@@ -7,6 +7,9 @@ require 'yaml'
 require 'bigdecimal'
 require 'date'
 
+require_relative 'help_text'
+require_relative 'config_loader'
+require_relative 'user_schema_builder'
 require_relative 'transaction'
 require_relative 'schema_registry'
 require_relative '../schemas/generic'
@@ -38,12 +41,12 @@ module FindSubscriptions
     end
 
     def run(argv)
-      options = parse_options(argv)
+      options, user_schemas = parse_options(argv)
 
       files = options.fetch(:files)
       raise ArgumentError, 'No files provided' if files.empty?
 
-      registry = build_registry
+      registry = build_registry(user_schemas)
       transactions = load_transactions(files, registry, options[:schema])
       transactions = filter_by_date_range(transactions, options[:from_date], options[:to_date])
       payee_normalizer = PayeeNormalizer.from_yaml(options[:known_payees_path])
@@ -85,7 +88,7 @@ module FindSubscriptions
 
     def inactive_cutoff(count, unit, today)
       case unit
-      when 'year'  then today << (count * 12)
+      when 'year'  then today << (count * 12) # Date#<< subtracts months
       when 'month' then today << count
       when 'week'  then today - (count * 7)
       end
@@ -138,10 +141,39 @@ module FindSubscriptions
       format('%.2f', decimal.to_f)
     end
 
+    # Three-layer precedence: built-in defaults → config file → CLI flags.
+    # Returns [options_hash, user_schemas_hash].
     def parse_options(argv)
-      options = default_options
+      handle_help(argv)
+      config = ConfigLoader.load
+      options = default_options.merge(config.options)
       define_option_parser(options).parse!(argv)
-      options
+      [options, config.schemas]
+    end
+
+    def handle_help(argv)
+      return print_full_help if argv.empty?
+      return unless argv.include?('--help') || argv.include?('-h')
+
+      print_targeted_or_full_help(argv)
+    end
+
+    def print_targeted_or_full_help(argv)
+      flag = other_long_flags(argv).first
+      return print_full_help unless flag
+
+      puts HelpFormatter.flag_help(flag) || "No help available for --#{flag}."
+      exit 0
+    end
+
+    def other_long_flags(argv)
+      argv.select { |a| a.start_with?('--') && a != '--help' }
+          .map { |a| a.delete_prefix('--') }
+    end
+
+    def print_full_help
+      puts HelpFormatter.full_help
+      exit 0
     end
 
     DEFAULT_KNOWN_PAYEES_PATH = File.expand_path('../../data/known_payees.yml', __dir__).freeze
@@ -156,28 +188,33 @@ module FindSubscriptions
       }
     end
 
-    def define_option_parser(options) # rubocop:disable Metrics/MethodLength
+    def define_option_parser(options)
       OptionParser.new do |opt|
         opt.banner = 'Usage: find-subscriptions --files a.csv,b.csv [--schema NAME]'
-        opt.on('--files FILES', 'Comma-separated list of CSV files') do |val|
-          options[:files] = val.split(',').map(&:strip).reject(&:empty?)
-        end
-        opt.on('--schema NAME', 'Force schema name (otherwise auto-detect)') do |val|
-          options[:schema] = val.strip
-        end
-        opt.on('--known-payees PATH', 'Known payees YAML; matched payees are filtered from output') do |val|
-          options[:known_payees_path] = val
-          options[:filter_known_payees] = true
-        end
-        opt.on('--inactive-for DURATION',
-               'Hide subscriptions with no transactions in DURATION (e.g. 6months, 1year, 3weeks)') do |val|
-          options[:inactive_for] = val.strip
-        end
-        opt.on('--min-amount AMOUNT', 'Hide subscriptions with a recurring charge below AMOUNT') do |val|
-          options[:min_amount] = val.strip
-        end
+        register_filter_options(opt, options)
         register_date_range_options(opt, options)
         register_presentation_options(opt, options)
+        register_config_options(opt)
+      end
+    end
+
+    def register_filter_options(opt, options) # rubocop:disable Metrics/MethodLength
+      opt.on('--files FILES', 'Comma-separated list of CSV files') do |val|
+        options[:files] = val.split(',').map(&:strip).reject(&:empty?)
+      end
+      opt.on('--schema NAME', 'Force schema name (otherwise auto-detect)') do |val|
+        options[:schema] = val.strip
+      end
+      opt.on('--known-payees PATH', 'Known payees YAML; matched payees are filtered from output') do |val|
+        options[:known_payees_path] = val
+        options[:filter_known_payees] = true
+      end
+      opt.on('--inactive-for DURATION',
+             'Hide subscriptions with no transactions in DURATION (e.g. 6months, 1year, 3weeks)') do |val|
+        options[:inactive_for] = val.strip
+      end
+      opt.on('--min-amount AMOUNT', 'Hide subscriptions with a recurring charge below AMOUNT') do |val|
+        options[:min_amount] = val.strip
       end
     end
 
@@ -199,11 +236,21 @@ module FindSubscriptions
       end
     end
 
-    def build_registry
+    def register_config_options(opt)
+      opt.on('--set-config PATH', 'Register a config YAML file for future runs') do |val|
+        ConfigLoader.set_config_path(val)
+        exit 0
+      end
+    end
+
+    # Built-in schemas are registered first so they take precedence during
+    # auto-detection. User schemas are appended after and can be forced via --schema.
+    def build_registry(user_schemas = {})
       registry = SchemaRegistry.new
       registry.register('american_express', Schemas.american_express)
       registry.register('navy_federal', Schemas.navy_federal)
       registry.register('generic', Schemas.generic)
+      user_schemas.each { |name, cfg| registry.register(name, UserSchemaBuilder.build(name, cfg)) }
       registry
     end
 

data/lib/find_subscriptions/config_loader.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'date'
+
+module FindSubscriptions
+  # Loads user configuration from a YAML file registered via --set-config.
+  #
+  # The pointer file (~/.find-subscriptions-config-path) stores the path to the
+  # actual config YAML. ConfigLoader.load returns a Result with parsed options
+  # and any user-defined schema definitions.
+  class ConfigLoader
+    CONFIG_POINTER_PATH = File.expand_path('~/.find-subscriptions-config-path').freeze
+
+    # Returned by ConfigLoader.load; carries parsed options and schema defs.
+    Result = Struct.new(:options, :schemas)
+
+    # Config YAML keys grouped by how they should be parsed.
+    # Amounts stay as strings so BigDecimal conversion happens at the filter site.
+    STRING_KEYS = %w[sort format schema inactive_for].freeze
+    BOOL_KEYS   = %w[filter_known_payees].freeze
+    PATH_KEYS   = %w[known_payees_path].freeze # expanded via File.expand_path
+    DATE_KEYS   = %w[from_date to_date].freeze # parsed to Date objects
+    AMOUNT_KEYS = %w[min_amount].freeze # kept as strings
+
+    def self.load(pointer_path: CONFIG_POINTER_PATH)
+      return Result.new({}, {}) unless File.exist?(pointer_path)
+
+      config_path = File.read(pointer_path).strip
+      return Result.new({}, {}) unless File.exist?(config_path)
+
+      raw = YAML.safe_load_file(config_path) || {}
+      Result.new(parse_options(raw), raw.fetch('schemas', {}))
+    end
+
+    def self.set_config_path(path, pointer_path: CONFIG_POINTER_PATH)
+      expanded = File.expand_path(path)
+      raise ArgumentError, "Config file not found: #{expanded}" unless File.exist?(expanded)
+
+      File.write(pointer_path, expanded)
+      puts "Config registered: #{expanded}"
+    end
+
+    def self.parse_options(raw)
+      options = {}
+      extract_strings(raw, options)
+      extract_bools(raw, options)
+      extract_paths(raw, options)
+      extract_dates(raw, options)
+      extract_amounts(raw, options)
+      options
+    end
+    private_class_method :parse_options
+
+    def self.extract_strings(raw, options)
+      STRING_KEYS.each do |key|
+        options[key.to_sym] = raw[key].to_s if raw.key?(key)
+      end
+    end
+    private_class_method :extract_strings
+
+    def self.extract_bools(raw, options)
+      BOOL_KEYS.each do |key|
+        options[key.to_sym] = raw[key] if raw.key?(key)
+      end
+    end
+    private_class_method :extract_bools
+
+    def self.extract_paths(raw, options)
+      PATH_KEYS.each do |key|
+        options[key.to_sym] = File.expand_path(raw[key].to_s) if raw.key?(key)
+      end
+    end
+    private_class_method :extract_paths
+
+    def self.extract_dates(raw, options)
+      DATE_KEYS.each do |key|
+        options[key.to_sym] = Date.parse(raw[key].to_s) if raw.key?(key)
+      end
+    end
+    private_class_method :extract_dates
+
+    def self.extract_amounts(raw, options)
+      AMOUNT_KEYS.each do |key|
+        options[key.to_sym] = raw[key].to_s if raw.key?(key)
+      end
+    end
+    private_class_method :extract_amounts
+  end
+end

data/lib/find_subscriptions/help_text.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module FindSubscriptions
+  # Detailed per-flag help strings, keyed by flag name (without leading --).
+  # Used by HelpFormatter to render full and targeted help output.
+  module HelpText
+    DESCRIPTIONS = {
+      'files' => <<~DESC.strip,
+        --files FILES
+            One or more CSV files to analyze, separated by commas.
+            Required. At least one file must be provided.
+            Example: --files transactions.csv,checking.csv
+      DESC
+      'schema' => <<~DESC.strip,
+        --schema NAME
+            Force a specific schema for parsing CSV files. If omitted, the
+            schema is auto-detected from the CSV headers.
+            Built-in schemas: american_express, navy_federal, generic
+            User-defined schemas can be added via a config file (see --set-config).
+            Example: --schema american_express
+      DESC
+      'known-payees' => <<~DESC.strip,
+        --known-payees PATH
+            Path to a YAML file listing payees to exclude from output. Useful
+            for ignoring loan payments, rent, or other expected recurring charges.
+            Example: --known-payees ~/.config/known_payees.yml
+      DESC
+      'inactive-for' => <<~DESC.strip,
+        --inactive-for DURATION
+            Hide subscriptions with no transactions within the given duration.
+            Format: NUMBER(year|month|week)[s]
+            Example: --inactive-for 6months, --inactive-for 1year, --inactive-for 3weeks
+      DESC
+      'min-amount' => <<~DESC.strip,
+        --min-amount AMOUNT
+            Hide subscriptions with a recurring charge below AMOUNT.
+            Useful for filtering out low-value noise transactions.
+            Example: --min-amount 5.00
+      DESC
+      'from' => <<~DESC.strip,
+        --from DATE
+            Only include transactions on or after DATE (format: YYYY-MM-DD).
+            Filters the transaction window before detecting subscriptions.
+            Example: --from 2025-01-01
+      DESC
+      'to' => <<~DESC.strip,
+        --to DATE
+            Only include transactions on or before DATE (format: YYYY-MM-DD).
+            Filters the transaction window before detecting subscriptions.
+            Example: --to 2025-12-31
+      DESC
+      'sort' => <<~DESC.strip,
+        --sort ORDER
+            Sort the output subscriptions by the given order. Default: first_desc
+            Valid orders:
+              count_asc   — fewest occurrences first
+              count_desc  — most occurrences first
+              first_asc   — earliest first-seen date first
+              first_desc  — most recently first-seen first (default)
+              last_asc    — earliest last-seen date first
+              last_desc   — most recently last-seen first
+            Example: --sort last_desc
+      DESC
+      'format' => <<~DESC.strip,
+        --format FORMAT
+            Output format for the results. Default: text
+            Valid formats:
+              text  — human-readable table (default)
+              json  — JSON array of subscription objects
+              csv   — comma-separated values with headers
+            Example: --format json
+      DESC
+      'set-config' => <<~DESC.strip
+        --set-config PATH
+            Register a YAML config file for future runs. Options in the config
+            file serve as defaults that CLI flags can override.
+            Supported keys: sort, format, known_payees_path, min_amount,
+              from_date, to_date, filter_known_payees, schema, inactive_for.
+            Add user-defined schemas under a top-level 'schemas:' key.
+            Example: --set-config ~/.find-subscriptions.yml
+      DESC
+    }.freeze
+  end
+
+  # Formats help output for the CLI: full help and per-flag targeted help.
+  module HelpFormatter
+    BANNER = <<~BANNER
+      find-subscriptions — detect recurring charges in your bank/credit card exports
+
+      Usage: find-subscriptions --files a.csv,b.csv [OPTIONS]
+    BANNER
+
+    def self.full_help
+      sections = HelpText::DESCRIPTIONS.map { |_key, desc| desc }
+      "#{BANNER}\n#{sections.join("\n\n")}\n"
+    end
+
+    def self.flag_help(flag_name)
+      HelpText::DESCRIPTIONS[flag_name]
+    end
+  end
+end

data/lib/find_subscriptions/user_schema_builder.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'schema_registry'
+require_relative 'transaction'
+
+module FindSubscriptions
+  # Builds a CsvSchema from a user-provided YAML configuration hash.
+  #
+  # Supported direction strategies:
+  #   positive_debit   — positive amounts are outgoing (e.g. AmEx)
+  #   negative_debit   — negative amounts are outgoing (e.g. generic bank export)
+  #   indicator_column — a separate column holds "Debit"/"Credit" labels
+  class UserSchemaBuilder
+    BASE_REQUIRED_KEYS = %w[required_headers amount_key direction date_column date_format payee_column].freeze
+
+    # Simple direction lambdas: amount sign alone determines debit/credit.
+    # indicator_column is handled separately since it needs config context.
+    DIRECTION_STRATEGIES = {
+      'positive_debit' => ->(_row, amount) { amount.positive? ? :debit : :credit },
+      'negative_debit' => ->(_row, amount) { amount.negative? ? :debit : :credit }
+    }.freeze
+
+    def self.build(name, config)
+      validate_base!(name, config)
+      CsvSchema.new(
+        required_headers: config.fetch('required_headers'),
+        amount_key: config.fetch('amount_key'),
+        direction: build_direction(name, config),
+        mapping: build_mapping(config)
+      )
+    end
+
+    def self.validate_base!(name, config)
+      missing = BASE_REQUIRED_KEYS - config.keys
+      return if missing.empty?
+
+      raise ArgumentError, "Schema '#{name}' missing required keys: #{missing.join(', ')}"
+    end
+    private_class_method :validate_base!
+
+    def self.build_direction(name, config)
+      strategy = config.fetch('direction')
+      return DIRECTION_STRATEGIES[strategy] if DIRECTION_STRATEGIES.key?(strategy)
+      return build_indicator_direction(config) if strategy == 'indicator_column'
+
+      raise ArgumentError,
+            "Schema '#{name}' has unknown direction: #{strategy.inspect}. " \
+            'Valid: positive_debit, negative_debit, indicator_column'
+    end
+    private_class_method :build_direction
+
+    def self.build_indicator_direction(config)
+      col = config.fetch('indicator_column') do
+        raise ArgumentError, 'indicator_column direction requires indicator_column key'
+      end
+      debit_val = config.fetch('debit_value', 'Debit')
+      ->(row, _amount) { row[col]&.strip == debit_val ? :debit : :credit }
+    end
+    private_class_method :build_indicator_direction
+
+    # Returns a lambda that closes over the column/format config so CsvSchema
+    # can call it without knowing the schema structure.
+    def self.build_mapping(config)
+      date_col  = config.fetch('date_column')
+      date_fmt  = config.fetch('date_format')
+      payee_col = config.fetch('payee_column')
+      ->(row, signed_amount) { map_row(row, signed_amount, date_col, date_fmt, payee_col) }
+    end
+    private_class_method :build_mapping
+
+    def self.map_row(row, signed_amount, date_col, date_fmt, payee_col)
+      Transaction.new(
+        date: Date.strptime(row[date_col], date_fmt),
+        payee: row.fetch(payee_col).to_s.strip,
+        amount: signed_amount,
+        raw: row
+      )
+    end
+    private_class_method :map_row
+  end
+end

data/lib/find_subscriptions.rb

@@ -1,4 +1,29 @@
 # frozen_string_literal: true
 
-# Entry point for FindSubscriptions: subscription detection from bank/credit CSV exports.
+# FindSubscriptions detects recurring charges in bank and credit card CSV exports.
+#
+# The main entry point for consumers of the library is {FindSubscriptions::CLI}.
+# CSV parsing is handled by {FindSubscriptions::CsvSchema} and {FindSubscriptions::SchemaRegistry}.
+# Repeat-charge detection lives in {FindSubscriptions::Detectors::RepeatCharges}.
+#
+# @see FindSubscriptions::CLI
+# @see FindSubscriptions::ConfigLoader
+# @see FindSubscriptions::UserSchemaBuilder
+module FindSubscriptions
+end
+
 require_relative 'find_subscriptions/transaction'
+require_relative 'find_subscriptions/schema_registry'
+require_relative 'find_subscriptions/payee_normalizer'
+require_relative 'find_subscriptions/help_text'
+require_relative 'find_subscriptions/config_loader'
+require_relative 'find_subscriptions/user_schema_builder'
+require_relative 'schemas/generic'
+require_relative 'schemas/american_express'
+require_relative 'schemas/navy_federal'
+require_relative 'detectors/known_payees'
+require_relative 'detectors/repeat_charges'
+require_relative 'output/stdout_reporter'
+require_relative 'output/json_reporter'
+require_relative 'output/csv_reporter'
+require_relative 'find_subscriptions/cli'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: find-subscriptions
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Jeffrey Baird
@@ -70,7 +70,7 @@ description: |
   A CLI tool that analyzes CSV files from banks and credit cards to detect
   subscription charges based on known payees and recurring transaction patterns.
 email:
-- jeffreybaird@hey.com
+- jeff@jeffreyleebaird.com
 executables:
 - find-subscriptions
 extensions: []
@@ -83,9 +83,12 @@ files:
 - lib/detectors/repeat_charges.rb
 - lib/find_subscriptions.rb
 - lib/find_subscriptions/cli.rb
+- lib/find_subscriptions/config_loader.rb
+- lib/find_subscriptions/help_text.rb
 - lib/find_subscriptions/payee_normalizer.rb
 - lib/find_subscriptions/schema_registry.rb
 - lib/find_subscriptions/transaction.rb
+- lib/find_subscriptions/user_schema_builder.rb
 - lib/output/csv_reporter.rb
 - lib/output/json_reporter.rb
 - lib/output/stdout_reporter.rb