Provider Import Adapter#

Account::ProviderImportAdapter is the shared import layer that all per-provider investment activity processors delegate to when persisting trades and cash transactions 1. It provides two public write methods — import_trade and import_transaction — and handles idempotent deduplication, type-collision guards, skip protection, and investment activity label detection. Provider-specific processors (SnapTrade, IndexaCapital, IBKR, Trading212) normalize raw provider data — including sign convention — before calling into the adapter.

Architecture: Two-Layer Design#

Each processor instantiates the adapter via @import_adapter ||= Account::ProviderImportAdapter.new(account) (SnapTrade at 2, IndexaCapital at 3).

import_trade and import_transaction#

import_trade#

Creates or updates an Entry with a Trade entryable for security-level activity (buys, sells, reinvestments, options) 4. Deduplicates by find_or_initialize_by(external_id:, source:) 5. When no explicit activity label is supplied, defaults investment_activity_label to "Buy" for positive quantity or "Sell" for negative 6.

import_transaction#

Creates or updates an Entry with a Transaction entryable for pure cash flows (dividends, contributions, withdrawals, fees, transfers, interest) 7. Uses the same deduplication strategy: find_or_initialize_by(external_id:, source:) 8. For investment accounts, auto-detects obvious labels (dividend, interest, fee, contribution) from the transaction name when none is passed 9.

Shared Behaviors#

• Idempotent deduplication: Re-importing the same activity updates the existing record rather than creating a duplicate 8.
• Type-collision guard: Raises ArgumentError if an existing entry with the same external_id has the wrong entryable type — e.g., a Trade where a Transaction is expected 10.
• Skip protection: Entries flagged as excluded, user_modified, or import_locked are never overwritten 11. The adapter records skipped entries for statistics collection 12.

Provider Activity Processors#

SnapTrade#

Maps 25+ SnapTrade activity types to Sure labels via SNAPTRADE_TYPE_TO_LABEL. Routes activity by type using two constants:

• TRADE_TYPES: BUY, SELL, REI, REINVEST, OPTION_BUY, OPTION_SELL, EXERCISED, ASSIGNED → import_trade
• CASH_TYPES: DIVIDEND, DIV, CONTRIBUTION, WITHDRAWAL, TRANSFER_*, INTEREST, FEE, TAX, CASH → import_transaction

IndexaCapital#

Maps types via ACTIVITY_TYPE_TO_LABEL. Same structure: TRADE_TYPES include BUY, SELL, REINVEST; CASH_TYPES include the remaining cash flow types.

IBKR and Trading212#

Both providers have their own ActivitiesProcessor implementations following the same pattern 13. IBKR receives data pre-split into trades and cash_transactions keys; Trading212 separates at the payload level with raw_orders_payload, raw_dividends_payload, and raw_transactions_payload.

Sign Convention and normalize_cash_amount#

Sure's convention for Transaction entries: amount < 0 = cash inflow (money in); amount >= 0 = cash outflow (money out) 14.

Each processor normalizes the raw provider amount before calling the adapter. The two processors use opposite normalization for inflows and outflows:

SnapTrade normalize_cash_amount: inflows → -amount.abs, outflows → +amount.abs — conforming to Sure's sign convention where cash in is negative.

IndexaCapital normalize_cash_amount: the opposite — inflows → +amount.abs, outflows → -amount.abs. This is inverted relative to the SnapTrade/Sure convention and relative to the Transaction sign semantics.

⚠️ Sign inconsistency: The two processors apply mirrored sign conventions. When debugging import amounts or adding a new provider, confirm which convention the adapter expects and align accordingly.

Trade Quantity Signs#

Both processors force sell-side types to negative quantity and buy-side to positive, using SELL_SIDE_TYPES constants:

• SnapTrade SELL_SIDE_TYPES: SELL, OPTION_SELL, ASSIGNED 15
• IndexaCapital SELL_SIDE_TYPES: SELL 16

The adapter then sets investment_activity_label based on quantity > 0 ? "Buy" : "Sell" when no explicit label is passed 6.

Key Source Files#