Most expense trackers ask you to type. Masareef's auto-track reads the alert your bank already sent you and books it. This article is the whole design: what each platform actually permits, the rules that survived contact with real banks, and the failures that paid for them. There is no product source here, only the ideas and the shapes, which are the parts worth copying.
The one principle everything else follows from#
A wrong row is visible. A missing row is invisible.
If the app books something incorrectly, you see it and delete it. If the app silently refuses a real alert, there is no row, no trace, and no evidence anything ever arrived. You find out weeks later while reconciling by hand, and you cannot tell whether the bank failed or the app did.
So there are three outcomes, deliberately unequal:
| Outcome | When |
|---|---|
| Book it | a movement that can be verified: known sender and a money-shaped amount |
| Hold for review | anything ambiguous; you settle it in one tap |
| Drop | only what can never be a transaction, whatever else it says |
Every widening of drop is a candidate for silent loss and has to be argued on those terms. That decided almost every hard call below.
Android: you get the firehose, and you must not drink it#
Android offers a notification listener and, on a sideloaded build, the SMS receiver. The listener is the interesting one, and the first thing to understand is that you cannot subscribe to one app. Grant the permission and the OS hands you every notification on the device: chat apps, music, mail, all of it. There is no per-app opt-in to decline.
That single fact drives the privacy design. The pipeline:
notification / SMS
→ native pre-filter (cheap, in Java, before anything is stored)
→ durable spool on disk (survives the process being killed)
→ headless JS gate (the real rules)
→ parser
→ book · hold · dropDisk first, always. The native side commits the record synchronously and takes a wake lock before handing anything to JavaScript. Android is free to kill the process between the notification arriving and your code running, and anything held only in memory at that moment is money the user spent and will never see.
// Shape, not source. The ordering is the whole point.
fun onNotificationPosted(sb: StatusBarNotification) {
if (!allowedPackages.contains(sb.packageName)) return // refuse on package alone
val haystack = sb.title + "\n" + sb.text + "\n" + sb.bigText
if (!prefilter.matches(haystack)) return
spool.commitSync(haystack, sb.packageName, sb.postTime) // disk BEFORE anything else
wakeLock.acquire(TASK_BUDGET_MS)
HeadlessJs.start("autotrack") // only now wake JS
}A refusal must leave no record of any kind#
An early build kept a diagnostics tally of ignored apps ("Yahoo 1,114×, Spotify 664×") to prove the app ignored them. It read as surveillance, and it was right to. Keeping a running count of Spotify to prove you do not watch Spotify is a contradiction no caption can fix. The counter was deleted and the stored key purged on upgrade, and a test now asserts that an excluded source leaves a trace of length zero.
The native pre-filter, and the property that keeps it honest#
Running the full rules in JavaScript for every notification on the phone is a battery problem, so a compiled pattern runs natively first. The trap is obvious once stated: two filters, two sets of rules, and they drift.
Two things prevent it.
The pattern is generated from the JavaScript rule lists, never hand-copied. A smarter rule then reaches binaries already installed the next time the JS publishes a new pattern, with no native release.
And one property, pinned by a test:
Anything the JS gate would keep, the native filter must also keep. The reverse is fine: native is deliberately looser.
That asymmetry is the principle from the top, expressed as a rule about two layers. A native filter that is too generous costs a wasted wake-up. One that is too strict costs a transaction.
Two limits fell out of it, both easy to get wrong:
- Only unconditional rejections may be mirrored. "You have won a prize" is never a transaction, so refusing it earlier loses nothing. A conditional rule ("looks like an advert and the number is not money-shaped") depends on information the native side cannot see, so it stays in JS.
- The two sides do not read the same text. JS parses one line, the newest in a thread. Native scans the whole collapsed blob, because that is the only form in which a "2 new messages" rollup carries its payment at all. Banks post marketing and charge alerts from the same short code, so an unconditional ad refusal would let an unread advert veto a real charge posted after it. That is the invisible loss, on the bank most of the user's transactions come from.
The rules that real banks taught#
Marketing rides ordinary verbs. A promo filter that only rejects when no movement verb is present will not save you, because a bank pitches its own products in perfectly ordinary sentences: "exclusive perks when you purchase the …". The verb fires and the blast walks through every gate.
What works is an intersection, and neither half is safe alone:
// An advert that never prints money beside a figure, and carries no reference
// and no masked account, cannot be a receipt.
if (isAutomated && hasPromoMarkers && !amountIsMoneyShaped) return DROPPromo vocabulary on its own rides plenty of genuine receipts ("earn double reward points"). A non-money-shaped amount on its own is the ordinary hold case. Only the intersection is safe to drop. And isAutomated matters: a human who types "50 off at the offer" into the paste box means it.
A marker list is a spelling list. One campaign got through because the rule read t&c apply and the message ended T&Cs apply., missed by one character. Both spacings, both apostrophe habits and the plural are all in the wild. When a marker fails, suspect the spelling before the logic.
A deadline is not an amount. "available only until August 8, 2026" scored 2026 as the figure. Date-awareness has to look back across a day number, not only at the words immediately beside it.
The notification shade writes text the sender never sent. Android's own [2 unread] rollup gets prepended exactly where an amount scorer looks, and the "2" becomes a transaction. Strip the OS chrome before anything reads the body.
Name the half that actually failed. A hold chip reading "Unverified sender" fired whenever either the sender or the amount check failed, so a perfectly matched bank alert with an odd amount accused the user's own bank of being a stranger. They are separate questions and now produce separate reasons, from one helper that drives both the chip and the booking gate, so they can never disagree.
Held is not a bin. Every card you must dismiss trains you to stop reading the queue, which is how the next real capture gets swiped away unread. A queue is only worth having if everything in it deserves a decision.
"Is the app alive?" is not a question your state store can answer#
A message arriving while the app is not in front takes one of two routes: hand it to the foreground drain, or do the work in the background task. Choosing by reading the user out of the global store is wrong, and subtly so: module state outlives the React tree. Android destroys the Activity while keeping the process alive, and on a phone with spare RAM that is the ordinary "I closed the app" state. The store still names a signed-in user long after the component that owns the drain unmounted, so the task pushes to an inbox nobody is listening to and returns.
Nothing is lost (the next foreground recovers it), but the user spent money and got no notification, which is indistinguishable from the app having missed it.
Route on whether the drain is actually subscribed, never on whether a user is in memory:
// Refcount live subscribers per event label. A mounted diagnostics screen
// is not a working drain, so the label matters.
const canHandInline = hasListener(INBOX_DRAIN) && isHydrated()Undercounting is the dangerous direction: a double cleanup driving the count negative would route live captures down the killed-app path.
iOS: state the impossibilities first#
This is where most write-ups go vague. Concretely, on iPhone:
- There is no notification listener. A bank's own app push is unreachable by any listener an app can hold. The one opening is iOS 27's Notification trigger in Shortcuts, which can hand an alert to the same intent; it only sees what the app shows as a notification, so roughly half of what Android captures is still not a capture surface on iOS.
- There is no SMS-reading API. The message-filter extension sees SMS from unknown senders and then cannot tell you: it may not write to disk and may not write the shared container the app reads. Its only exit relays the sender and body to a URL fixed in
Info.plist, which means shipping raw bank SMS through your own server. Rejected: it inverts on-device redaction, and an extension that always returns.allowwhile forwarding everything is not a spam filter, which is a real review risk. - Shortcuts could not read notifications before iOS 27, only messages, mail and Wallet payments. Since iOS 27 a Notification trigger can, and one automation covers Messages, Wallet and the country's bank apps. The app list is one signed file per country, capped at 30: a list of 1,527 froze the Shortcuts editor for good on iOS 27.2.
So iOS auto-track covers bank SMS, plus bank-app alerts on iOS 27 and later where the app posts a notification, and the setup screen says exactly that rather than implying parity.
The one iOS route that works#
A Shortcuts personal automation ("When I get a message", set to run immediately) calling an App Intent the app publishes:
bank SMS
→ Shortcuts personal automation ("When I get a message", Run Immediately)
→ App Intent (openAppWhenRun = false)
→ append one raw line to a spool file on disk
→ one collapsed local notification, however many arrived
→ next foreground: drain the spool through the SAME gate and parser as AndroidFive things carry that design.
The Swift does not parse. The intent writes a raw record and stops. Every rule (the sender allowlist, the promo intersection, hold reasons, redaction) stays in the shared TypeScript, where the test suite already pins it. A Swift parser would be a second set of rules, and the first time the two disagreed the disagreement would be invisible.
The drain reuses the Android SMS entry point rather than reimplementing it. That function already takes exactly this shape (a raw body, a sender id, a post time), so iOS became a fourth caller of an existing route, not a parallel pipeline.
The intent lives in the main app target, not in a module. Xcode extracts App Intent metadata per target, and intents compiled into an autolinked pod routinely go missing from the Shortcuts action list. A second benefit falls out of it: running in the app's own process means the spool lands in the app's own container, so no App Group is needed.
The intent returns nothing. It once returned a Bool, and the first run outside the editor asked "Allow … to output 1 boolean?", a prompt a locked-phone automation can never answer, so the capture was swallowed. A failed write throws instead.
// Shape only. Returning a value is the bug; throwing is the contract.
func perform() async throws -> some IntentResult {
try spool.append(body: messageBody, sender: senderId, at: .now)
await notifier.postCollapsedBanner()
return .result() // nothing to confirm, nothing to prompt about
}Nothing is destructive before it is safe. A record is removed only after its handler returns, so a process death replays whatever was in flight, and a replay is a no-op, because the dedupe key derives from the message text and its original post time. The one hazard replay cannot survive is a record that kills the process every time, so each carries an attempt count written to disk before it is handled, and is dropped, loudly, after three.
A bug the tests caught and the comments did not: a failing record originally stayed at the head of the file, so the walk retried it instead of moving on and starved everything queued behind it. A failed record now rotates to the back and the pass stops when the head comes round again: one attempt per pass, not three in a row.
When the OS blanks the text#
A field report: notification access granted, background running allowed, the reader alive, a message received minutes ago, and the last captured transaction two days old. A real card charge never became a row. The parser was innocent; the same text books correctly through every delivery channel.
Android's classifier had decided the user's bank alerts looked like one-time codes and replaced every body with a placeholder before the listener ever saw it. There is no app-side read of that text in a store-distributed build: it is a system role a finance app cannot hold. Hundreds of alerts, blanked, in silence.
What was actually broken was ours, and it was the silence. The app counted hidden alerts and posted a notice once per device, ever, on the theory that repeating a persistent condition teaches people to ignore you. That theory is right for a condition that costs nothing and wrong for one that costs a transaction every time it fires.
The rules now:
- Blinded is a health state of its own, ranked below "nothing is arriving at all" and above "at risk", and it is live-gated: a phone hit once last spring reports healthy without the user clearing anything.
- The notice returns weekly while it is still happening, from the background gate and from the app root, sharing one slot so they cannot double-post.
- Daily, not weekly, once capture is producing nothing at all. Weekly is the pace for a degraded app; a device blanking everything is not degraded, it is dead, and weekly means six-day stretches with every charge dropped in silence. "Dead" is measured by money-shaped messages seen and not captured since the last capture, so it clears itself the moment capture works again.
- The explanation books the money it cannot read. Naming the cause does nothing for the charge that was blanked an hour ago. The message is still on the phone, and two taps is the difference between a lost transaction and a booked one.
The capture route that starts outside the app#
Every import route began with "be in the app": open it, find the paste screen, get sent to the SMS app, find the thread, long-press, select, share, find the app in the sheet. Seven steps, and the first two are the ones a person reading a bank SMS has not taken.
Android's process-text action inverts it. An app that declares it is offered by name in the floating toolbar the OS draws over any selected text: Messages, WhatsApp, mail, the bank's own app, a browser. Select the message, tap the app. The text lands in the same importer and runs the same parser as everything else, and ends where every capture ends.
Three things about it fail silently, which is exactly why they are worth writing down:
- Read the extra as a
CharSequence, never aString. A styled selection (a linkified amount, a bolded merchant) arrives as a span, and the string getter returns null. The feature would die on precisely the messages worth capturing. CATEGORY_DEFAULTis not optional. An implicit intent never matches a filter without it, and the toolbar entry simply does not appear, against a manifest that reads perfectly correctly.- Alternate launcher icons disable the main activity. A disabled component resolves no intent, so choosing a different app icon silently removed the app from the share sheet. Every icon alias has to carry the same intent filter, checked by deep-equality against the real one so that narrowing one can never pass.
It is also policy-safe by construction: it reads text the user selected and acted on, never touches the SMS store, and needs no permission.
What I would carry to any project like this#
- Rank your failure modes before writing a single rule. Wrong-and-visible beats missing-and-invisible, and once that is settled most arguments answer themselves.
- Commit to disk before you do anything clever. Parsing, waking JS and the network can all be interrupted. Disk first, then everything else.
- One set of rules. If a second layer must exist for performance, generate it from the first and pin the superset property with a test.
- Never route on state that outlives the tree. Ask whether the listener is subscribed, not whether a value is still in memory.
- Say what the platform cannot do, inside the product. iOS covers SMS, and bank-app notifications only on iOS 27 and later, and the setup screen says so. A feature that quietly does half of what its name implies is worse than one that names its own limits.
- A refusal should leave no trace. If you would not want a screenshot of your diagnostics posted on a forum, do not collect it.
- Silence is a bug, and it has a severity. Anything that can fail invisibly needs a health state, an escalation, and a way for the user to recover the specific thing that was lost.
The app this describes is Masareef, a free expense tracker for Android and iPhone. Install Masareef and it opens the right store for your phone.