transaction-signal

Local, deterministic extraction of transaction signals from financial messages for JavaScript and React Native.

This library answers one core question:

Is this message a real transaction signal right now?

Features

• Local parsing (no network calls)
• Deterministic rule-based engine (no ML)
• Transaction amount and merchant extraction
• Single transaction time output (transaction_time)
• Category inference (category, category_confidence)
• Intent and false-positive control (transactional vs marketing)
• Indian banking format support (UPI, card, IMPS, NEFT, clearing)
• TypeScript types and ESM/CJS builds

Installation

npm install transaction-signal

Usage

As a library

import { analyzeSignal } from 'transaction-signal';

const signals = analyzeSignal({
  body: 'Dear Customer, Rs.137.00 has been debited from account to VPA merchant...',
  sender: '[email protected]',
  subject: 'Transaction Alert',
  rule_version: 'v1',
});

console.log(signals[0]);
// {
//   transaction_time: '2026-02-07T18:30:00',
//   direction: 'Outflow',
//   approx_amount_minor: 13700,
//   merchant_hint: 'RAJDEEP SALES CORPORATION',
//   category: 'Misc',
//   category_confidence: 0.3,
//   state: 'Completed',
//   confidence: 0.85,
//   intent: 'transactional',
//   vetoed: false
// }

As a CLI

# using npx
npx transaction-signal email.txt

# after global install
transaction-signal email.txt

# local dev
npm run cli email.txt

The CLI reads file content and prints JSON output.

Output fields

Each call returns Signal[].

• transaction_time: single transaction time field. Format is YYYY-MM-DD if message time is unavailable, else YYYY-MM-DDTHH:mm:ss
• direction: Inflow or Outflow
• approx_amount_minor?: inferred amount in minor units (paise)
• merchant_hint?: extracted merchant/counterparty
• category?: one of transaction categories (including Investment)
• category_confidence?: confidence for category inference
• state: Completed | Pending | Blocked | Refunded
• confidence: overall signal confidence (0.05 to 0.85)
• intent?: transactional | marketing | unknown
• vetoed?: hard veto for marketing/noise

Development

npm install
npm run typecheck
npm test
npm run build

See DEVELOPER.md for architecture, design, and contributor workflow.

License

MIT