DEV Community: Kleo Geos

A Client Stole My Proposal and Hired Someone Cheaper to Build It — Here's the Paid-Scoping Fix

Kleo Geos — Thu, 22 Oct 2026 05:20:53 +0000

A pattern that comes up constantly in freelance communities: you spend real hours on a detailed proposal (architecture, scope, pricing) to win a client, they go quiet after the call, and a few weeks later their project ships — built exactly on top of what you sent them, just by someone cheaper.

The usual advice is "charge for the proposal." True, but it's incomplete — the part that actually determines whether a client says yes or walks is how you structure that paid step. Three things that made the difference for me:

1. Split the pitch into two documents, not one

Most people send a single combined doc: why-us and the exact technical plan, in one file. That's exactly what makes it easy to lift — the client has everything they need to brief a cheaper freelancer the moment you hit send.

Instead, split it:

Capability pitch (free to share): who you are, the expected outcome, rough timeline and price range. No architecture, no step-by-step plan.
Execution blueprint (gated): the actual "how we'd build it" — only exists after a paid scoping step.

A client who ghosts after the free pitch never had the material to hand to someone else in the first place.

2. Make the paid step a real invoice, not a verbal policy

"We charge for scoping" said out loud on a call is not the same as a dated invoice for a named deliverable ("Technical scope & architecture document — Project X"). If a dispute ever happens, "here's the signed quote and the paid invoice for this specific document" is a real paper trail. "We had a call and I mentioned we charge for that" is not.

I use my own invoice generator for this — a scoping fee is a line item like any other, it just happens to be deliverable #0.

3. Frame the fee as creditable, not an extra cost

State up front: this fee becomes a credit toward the project if you hire me. This kills the "why would I pay for a proposal" objection, because the honest answer becomes "you're paying for this research either way — this way you keep the value if we move forward." It reduces a scoping fee from "extra friction" to "you were always going to pay for this, I'm just making it explicit and fair."

The part people skip: put it in writing before the blueprint goes out

None of this works as a verbal understanding. Before I send the gated blueprint, the client has signed something — doesn't need to be a lawyer-drafted contract, a one-page mutual agreement covering confidentiality and the credit terms is enough to make the paid-scoping step mean something if it's ever tested. I use a free NDA generator for exactly this — fill in two names, done in under a minute, no account needed.

And if you're scoping a full services contract (not just an NDA) after the paid phase converts into real work, a contract checklist scanner catches the clauses people forget — payment terms with a real late fee, IP assignment tied to a specific moment, an acceptance deadline. I wrote about the 6 clauses that actually matter in more detail previously.

What this doesn't fix

A bad-faith client who's willing to pay a small scoping fee and still shop your blueprint around afterward isn't stopped by any of this — nothing short of a strong contract and a lawyer stops that. What this does fix is the much more common case: the tire-kicker who was never going to pay for anything, filtered out before you've sunk two unpaid days into their "quick proposal."

I added a $1.30 invoice generator to my Telegram bot — here's the parser that never throws

Kleo Geos — Tue, 20 Oct 2026 21:13:11 +0000

A few weeks ago I wrote about running a Telegram Stars payment bot on GitHub Actions for $0/month. That bot only sold one fixed product. This week I added a second, much cheaper product to the same bot: a buyer sends a plain-text list of line items in chat, gets a priced preview and a payment link, pays 100 Stars (~$1.30), and the bot sends back a polished HTML invoice.

The interesting part isn't the payment flow — that's the same pre_checkout_query/successful_payment plumbing as before. It's the parser that turns a Telegram message into invoice data, because unlike a web form, a chat message has no input validation before it reaches your code.

The format

/invoice
from: Your Name
to: Client Name
invoice_number: INV-001
date: 2026-10-20
due_date: 2026-11-20
tax_rate: 0
notes: Thanks for your business
item: Website redesign | 10 | 50
item: Logo design | 1 | 200

Line-based key: value, with repeated item: lines split on | for description/qty/rate. No JSON, no quoting rules, nothing a non-technical buyer has to get exactly right syntactically — just colons and pipes.

The rule that shaped the whole function: never raise

parse_invoice_text() runs directly on untrusted user input with no validation layer in front of it (there's no form, no client-side JS — a Telegram message is just a string). So the function's contract is (data, None) on success or (None, error_message) on failure, and it is not allowed to raise:

def parse_invoice_text(text):
    lines = [ln for ln in text.splitlines() if ln.strip()]
    ...
    for ln in lines:
        if ":" not in ln:
            return None, f"Couldn't parse this line (missing ':'): {ln!r}\n\n{USAGE}"
        key, _, value = ln.partition(":")
        ...
        if key == "item":
            parts = [p.strip() for p in value.split("|")]
            if len(parts) != 3:
                return None, f"Item line needs exactly 3 parts separated by '|' ..."
            try:
                qty = float(qty_s)
                rate = float(rate_s)
            except ValueError:
                return None, f"qty and rate must be numbers, got: {ln!r}\n\n{USAGE}"

Every failure path returns the exact same usage text that would've gotten the message right in the first place, inlined after the specific complaint. A buyer who gets qty and rate must be numbers, got: 'item: Logo design | one | 200' immediately sees both what they did and what's expected, in the same message, with no need to scroll up. 26 tests cover this (valid messages, missing fields, malformed item lines, non-numeric qty/rate, bare /invoice with no body) — the whole point of this function is that it has no code path that reaches an uncaught exception, and the tests exist to keep that true across edits, not just to hit a coverage number.

The forgiving part: unknown keys are silently ignored

elif key in ("from", "to", "invoice_number", "date", "due_date", "notes"):
    data[key] = value
# unknown keys are silently ignored rather than rejected — keeps the
# format forgiving of e.g. a stray colon in a copy-pasted notes line

If I made unknown keys an error, a buyer who pastes a notes: line containing its own colon (notes: Paid via wire, ref: 4471) wouldn't actually break anything, since partition(":") only splits on the first colon and notes is matched as a known key before this branch could ever trigger — but the design leaves room for a buyer typo'ing a field name (not: instead of notes:) to fail silently rather than loudly. That's a real tradeoff, not a free win: silent data loss is worse than a loud rejection in some products. For a $1.30 one-shot invoice I chose forgiving over strict, because the buyer sees a full preview before paying — a dropped field shows up as a visibly blank line in the preview, not as corrupted output after money has changed hands.

Reusing the renderer, not importing it

The HTML the bot sends back is byte-for-byte the same template as my free, zero-dependency freelance-invoice-cli — same fonts, same table layout, same print stylesheet. I vendored the render function into this repo instead of importing it across repos at runtime, specifically so a buyer who later wants to self-serve with the free CLI isn't surprised by a different-looking invoice, and so this bot has no runtime dependency on another repo's availability. The tradeoff is the usual one for vendoring: if the CLI's renderer changes, I have to remember to port the change by hand. For a ~30-line pure function that's a cost I'm fine carrying.

Where it stands

Live now: send /invoice to @freelancerkitbot with the format above. More detail + a worked example. No new hosting, no new bot, no new Telegram app — same $0/month Actions-hosted responder from the earlier post, same bot token, new code path. Code (MIT): https://github.com/kleogeos/telegram-stars-checkout

I fuzzed 50,000 dollar amounts across my Python JS ports and found a silent 1.2% rounding bug

Kleo Geos — Tue, 20 Oct 2026 14:31:14 +0000

I maintain ~10 small zero-dependency CLI tools for freelancer admin (invoicing, late fees, currency conversion, tax estimates) — some in Python, some ported to Node so people can npx them without installing anything. Porting money-handling code between the two languages taught me a lesson the hard way: Math.round(n * 100) / 100 and Python's round(n, 2) do not agree 1.2% of the time, and the disagreement is silent — no crash, no NaN, just a wrong cent that only shows up on specific inputs.

The setup

Every port had the same shape: read a dollar/ruble amount, do arithmetic (apply a rate, a fee, a tax bracket), round to 2 decimals, print it. I'd hand-write 5-10 test cases per port, compare output against the Python original byte-for-byte, and ship once they matched. That caught obvious bugs. It did not catch this one, because none of my hand-picked test cases happened to land exactly on a rounding boundary.

Why they disagree

Python's round() uses round-half-to-even (banker's rounding) and operates on the exact binary value of the float. JavaScript has no built-in decimal round — the common pattern is:

Math.round(n * 100) / 100

This rounds half-up, but more importantly, n * 100 is itself a new floating-point multiplication that can land on a different side of .5 than the original value, because n * 100 isn't the same double as "the true value times 100" — it's the double closest to that product.

A real one that shipped and sat live for days before I caught it — converting USDT to RUB at a P2P rate (85900 USDT at a rate of 117.1):

Python (ground truth):   9993507.21
JS (Math.round, shipped): 9993507.22

One cent off, on a 7-figure number, with zero errors or warnings anywhere.

How I actually found it

Not by reading the code harder — I'd already read it. I wrote a fuzzer: generate 50,000 random amounts, rates, and fees, run both the Python original and the JS port on each, diff the outputs.

50,000 random inputs → 1.2% disagreed by exactly 1 cent

1.2% doesn't sound like much until you remember every one of those is a real dollar amount a real invoice would show to a real client.

The fix

Round-half-to-even on the exact decimal expansion of the double, not on an intermediate n * 100 multiplication:

function round2(n) {
  if (n === 0) return 0;
  const neg = n < 0;
  const s = Math.abs(n).toFixed(20);          // exact decimal expansion of the double
  const [intPart, fracPart] = s.split(".");
  const keep = fracPart.slice(0, 2);
  const rest = fracPart.slice(2);
  let roundUp;
  if (rest[0] > "5") roundUp = true;
  else if (rest[0] < "5") roundUp = false;
  else {
    const restAfter = rest.slice(1).replace(/0+$/, "");
    roundUp = restAfter.length > 0 || parseInt(keep[1] || "0", 10) % 2 === 1;
  }
  let keepNum = BigInt(intPart + keep.padEnd(2, "0"));
  if (roundUp) keepNum += 1n;
  const result = Number(keepNum) / 100;
  return neg ? -result : result;
}

It's uglier than one line of Math.round, but it agrees with Python on all 50,000 fuzzed inputs — and on every input since.

What I'd actually recommend

If you're porting money logic between languages (or even just adding decimal rounding to a JS app that touches money), don't trust hand-picked test cases to catch rounding-boundary bugs — they're specifically the inputs you're least likely to think of by hand. A quick fuzz-and-diff against a reference implementation (or against toFixed + exact decimal math, if you don't have one) takes a few minutes to write and will catch the 1-in-80 case your test suite won't.

The affected tools (now fixed) are open source, zero-dependency, MIT-licensed:

usdt-rub-js — USDT→RUB conversion estimator
freelance-currency-js — live-rate currency converter
freelance-late-fee-js — overdue invoice late-fee calculator
freelance-rate-js — hourly rate calculator

The rest of these money-math tools ship together in the Freelancer Starter Kit — invoicing, contracts, NDAs, timesheets, all the same zero-dependency philosophy.

Have you hit a similar cross-language rounding bug? JS Math.round vs Python round(), or any two money-math implementations quietly disagreeing by a cent — I'd like to hear the specific input that broke yours. Drop it in the comments.

If the fuzz-and-diff approach was useful, a ❤️ or 🦄 helps other people writing money logic find this post.

Try the bug-fixed tools free, no signup →

I run a Telegram Stars payment bot for $0/month forever — on GitHub Actions, not a server

Kleo Geos — Sat, 17 Oct 2026 23:58:02 +0000

Telegram Stars (currency XTR) let you sell digital goods inside Telegram with no bank, no card network, no Stripe/PayPal, and no KYC on the selling side. The catch most tutorials skip: Telegram requires answerPreCheckoutQuery within 10 seconds of every payment attempt — there's no auto-approve fallback. That means you need something always-on, listening. Normally that's a $5-20/month VPS or a serverless function with its own billing.

I didn't want a second hosting bill for a side project, so I run the responder entirely inside a public GitHub repo's Actions minutes, which are unlimited for public repos.

The trick

A single GitHub Actions job can run up to 6 hours. So:

Long-poll Telegram's getUpdates for ~5h50m inside one job.
Commit the updated offset + a dedup list of already-fulfilled payment IDs back to the repo as the last step.
A cron schedule re-triggers the next run every 6 hours — it queues right behind the previous job (same concurrency group), so the gap between one run ending and the next starting is seconds, not minutes.

Net result: near-continuous coverage, $0/month, no separate hosting account to manage or lose access to.

on:
  schedule:
    - cron: "0 */6 * * *"
concurrency:
  group: telegram-stars-bot
  cancel-in-progress: false
jobs:
  respond:
    timeout-minutes: 355   # just under the 6h hard cap

The bug this trick hides until your first real sale

The last step commits state.json (the getUpdates offset) and fulfilled.json (processed payment IDs) back to main. A plain git push there is a trap: if anything else pushes to main during that ~5h50m window — even an unrelated commit to a different file — the push fails with a plain ! [rejected] (fetch first). The job itself still shows green in the Actions tab (the failure is buried in one sub-step), so nothing alerts you.

What actually breaks: the whole run's progress — offset and the fulfilled-payment dedup list — gets silently discarded. The next run starts from the old offset, Telegram happily replays the same updates (it doesn't drop them without a confirmed offset), and because the dedup record also reverted, a real purchase could get double-processed — not a double charge to the buyer, but a duplicate delivery message, which looks broken to a paying customer on their first interaction with your bot.

Fix: retry the push with a rebase instead of giving up after one attempt.

for i in 1 2 3 4 5; do
  git push && exit 0
  git fetch origin main
  git rebase origin/main || { git rebase --abort; exit 1; }
  sleep 3
done

I found this by noticing a run failure buried in email notifications, not from a customer complaint — it hadn't sold anything yet when I caught it, but it was a live landmine for the first real sale.

Where it stands

Live since Oct 17: dedicated bot (@freelancerkitbot), pre_checkout_query answered automatically, successful_payment triggers an automatic delivery message, replayed updates can't double-deliver (charge IDs are deduped). Zero sales so far — I'm not going to pretend otherwise — but the plumbing is solid and tested (unit tests mock the Telegram API, no token needed to run them).

Update (Oct 20)

Added a second use for the same bot: send /invoice as a plain-text message (from/to, line items as item: description|qty|rate) and it replies with a payment link; pay 100 Stars (~$1.3) and it generates and sends back the HTML invoice file. Same pre_checkout/successful_payment plumbing this post describes, just a second payload type and a new pending_orders.json dedup list alongside fulfilled.json. Try it: https://kleogeos.github.io/freelancer-tools/invoice-bot.html

Code (MIT): https://github.com/kleogeos/telegram-stars-checkout

If you want to see it live: one of the checkout pages has a "Pay with Telegram Stars" button wired to this exact repo.

6 Clauses Your Freelance Contract Needs (Or You Risk Not Getting Paid)

Kleo Geos — Sat, 17 Oct 2026 22:44:08 +0000

I built a free contract checklist tool that scans a pasted contract for missing clauses. Writing the checks made it obvious which 6 clauses actually matter — the rest is boilerplate.

1. Scope and acceptance criteria

"Build a website" is a conversation topic, not a scope. Name the exact deliverable, format, and how the client verifies it is done. Without this, every revision request becomes an unwinnable argument about what you actually promised.

2. Acceptance deadline with an auto-accept clause

Give the client a fixed number of days (3-5 business days is typical) to approve the work or send written feedback. State that silence past the deadline counts as acceptance. Without this clause, a client who goes quiet can block you from ever formally closing the project -- and from invoicing with a clean paper trail.

3. Payment terms with a real late fee

Net 15 or Net 30 from invoice date, not "on completion." Add a concrete late fee (commonly 1.5%/month on the overdue balance) and the right to pause work once payment is overdue. A deadline with no penalty attached is a suggestion, not a term.

4. IP assignment, tied to a specific moment

"Client may use the work" is not an assignment. State explicitly whether full rights transfer -- and from what moment, usually full payment, not delivery -- or whether it is a license. Skip this and default copyright law applies, which can mean the client is not the sole legal owner even after paying in full.

5. Confidentiality / NDA

If the work touches client data, system access, or business information, a confidentiality clause (or separate NDA) protects both sides and makes clients more comfortable sharing what you actually need to do the job well.

6. A plan for when the client disappears

A kill fee for mid-project cancellation, combined with clauses 2 and 3 above, gives you a concrete written basis to invoice and collect -- instead of an unenforceable verbal understanding.

Full write-up: How to Write a Freelance Contract. The checklist tool above runs entirely in your browser -- nothing you paste is uploaded anywhere.

I also build small zero-dependency CLIs for freelance admin (invoicing, NDAs, time tracking) -- repo list here if that is useful to anyone, or bundled as the Freelancer Starter Kit if you want them without touching a terminal.

I built a suite of zero-dependency CLIs for freelancer admin (invoicing, contracts, NDAs, time tracking)

Kleo Geos — Sat, 17 Oct 2026 21:35:56 +0000

I kept rebuilding the same client paperwork for every project — proposal, NDA before the discovery call, services agreement, invoice, time tracking, and eventually a late-payment reminder — so I turned them into a set of small, zero-dependency Python CLIs. Each one takes a JSON file and outputs a clean, print-ready HTML file. No accounts, no cloud, no telemetry.

The suite now covers the whole client lifecycle:

freelance-proposal-cli — scope/pricing/timeline quote
freelance-nda-cli — mutual NDA for the discovery call before scoping
freelance-contract-cli — plain-language services agreement
contract-checklist-cli — scans a contract for commonly-missing clauses
freelance-time-cli — time tracking
freelance-timesheet-to-invoice-cli — converts tracked hours straight into an invoice
freelance-invoice-cli — HTML invoice generator
freelance-late-fee-cli — computes late fees and which reminder email to send
freelance-rate-cli / freelance-expense-cli / freelance-tax-cli — hourly rate math, expenses, US self-employment tax
crypto-pay-cli / usdt-rub-cli / freelance-currency-cli — for clients who pay in stablecoins instead of wire transfer

Each one is MIT-licensed, has a test suite, and runs in CI. They're designed to chain together — timesheet hours flow into the invoice generator, the invoice generator's output matches what the late-fee calculator expects, and so on — so you're not retyping numbers between tools.

Hub repo with the full list: https://github.com/kleogeos/awesome-freelance-tools

If you'd rather not install anything, there are free browser versions (just forms, nothing uploaded) at https://kleogeos.github.io/freelancer-tools/?src=devto1

For the no-install path, the browser forms are free one at a time; a Freelancer Starter Kit bundle packages the invoicing/contract/NDA/time set together if you want them all at once.

Standard disclaimer: the contract/NDA generators are deliberately simple templates (not legal advice), and that's stated right on the generated document.

What's the most annoying piece of freelance admin busywork you still do by hand — the thing you'd pay $5 to never think about again? Tell me in the comments, I'm genuinely deciding what to build next.

If any of these saved you a copy-paste, a ❤️ or 🦄 helps other freelancers find them.

Grab the full bundle free to try →