Build Play Billing Machinery on android-kotlin-node

Google Play gives you a purchase token and a doorbell. Everything that decides whether a user is

actually entitled — reading real state from the Developer API, surviving duplicate and

out-of-order notifications, acknowledging inside a three-day window before Google auto-refunds

the purchase, and telling "cancelled" apart from "expired" — is yours to build, and every one of

those is a bug you find in production rather than in a test. This pack builds the whole rig for

an existing Android app: a Billing Library 9 client with no v7 ghosts in it, a server that is

the actual source of truth for entitlement, and a Play Console review preflight. Its

verification is the unusual part — a locally minted OIDC signing chain and a fake Play API prove

the push-authentication path and the entitlement state machine **without a Google account**.

**Status: `draft`. This pack has no receipt yet.** Every verified pack in this catalog publishes

a measured pass rate as M of N clean-room builds. This one does not have one, because the

harness has not run it. When it does, the receipt page will publish the pass rate, the measured

token volume and the measured per-run cost — and if it cannot pass, this pack does not get

listed. Until then, treat the numbers below as what they say they are: estimates.

Example use cases

• **An indie Android dev with a v7 integration and a deadline.** Google Play Billing Library 7

cannot be used for new apps or updates after **2026-08-31**. Existing installs keep

transacting, so nothing looks broken — right up until you try to ship a bug fix and the upload

is rejected. This pack lands on 9.1.0, which clears that gate and the 2027 one.

• **A developer who shipped iOS first** (often with this pack's sibling, `appstore-machinery`)

and now needs Android parity with **one** concept of "entitled" in their backend, not two

subtly different ones.

• **A subscription app that keeps seeing unexplained churn in its first week of purchases** —

which is what an unacknowledged-purchase bug looks like from the outside, because Google

refunds and revokes silently after three days.

• **A team migrating off RevenueCat** because per-revenue pricing stopped making sense at their

scale, and who need the entitlement logic they were renting to now exist in their own repo,

with tests.

• **An agency shipping billing into several client Android apps** — the same server, preflight

and acceptance suite re-stamped per client instead of re-solving Play's delivery semantics per

contract.

Scale envelope

Derived from the pinned architecture and Google's published limits, not from a load test.

Nothing here is measured by a receipt — this pack does not have one yet — so every number is

labelled as the engineering estimate it is.

• **Notification volume is per billing cycle, not per session.** A monthly subscriber generates

roughly 12 renewal notifications a year (annual: 1), plus one-off purchase, cancel, grace,

hold, pause and refund events. At **25,000 monthly subscribers** that is on the order of

**900–1,500 notifications/day** — Google sizes each at about 1 KB. **Estimate.**

• **The entitlement store.** A single Node process over `node:sqlite` on one volume, writing a

handful of rows per notification. At the volume above, the database is nowhere near the

constraint; **roughly 50,000–100,000 active subscribers** fits on one small Railway instance

before instance limits — not row counts — become the issue. **Estimate.**

• **The first ceiling is a burst, not a total.** The Play Developer API allows 200,000

requests/day per application *and* **3,000 queries/minute per bucket**. Steady-state renewal

traffic never approaches either. What does is a fan-out event — a price change or a policy

update that generates a notification for every subscriber at once — where one Play API read

per notification can cross 50/second. The daily quota is generous; the per-minute bucket is

the one that bites.

• **The second ceiling is a single point of failure**, and it is deliberate at this price: one

process, one volume, no clustering. Pub/Sub will retry a nacked push with backoff and holds

messages for **7 days by default (31 maximum)** — so a short outage is survivable by design

and a long one is why `reconcile.js` exists. The permanent blind spot is refunds: the voided

purchases API only looks back **30 days**, hard limit.

• **Upgrade path, in the order you'd actually need it:** (1) put a queue between `/rtdn` and the

Play API call so fan-out bursts are smoothed under the per-minute quota instead of racing it —

the handler is already idempotent, which is what makes this safe; (2) swap `store.js` for

Postgres, the only file that touches the database; (3) run multiple instances, which the first

two changes make possible. Request a quota increase from Google support only after (1), since

most quota pain is burst-shaped.

**What it costs to skip the pack (modelled twice over — read the caveat).** For the verified

packs in this catalog, this figure starts from a *measured* build. This pack has no receipt, so

its input is itself an estimate, and the result is an estimate built on an estimate. Taking

`appstore-machinery`'s measured shape as the anchor and repricing at Opus-class rates with no

cheap-tier routing, no parallel subagents and no prompt-caching discipline, the naive path

models out at roughly **$100–390 in API tokens, likely around $195**, against this pack's $149.

Honest reading: **do not buy this for the token savings.** At the low end it does not clear the

price, and the whole band rides on an exploration multiplier we are estimating. Buy it because

four of the five bug classes above are the silent kind — they cost you refunds and churn, not an

error message — and because the acceptance suite is what lets you migrate on Google's schedule

without re-deriving any of it.

**And the caveat that matters more than the arithmetic:** most buyers are not metered. If you

are on a $20/mo Claude plan, you pay $20 either way and your marginal token saving is roughly

zero. What the pack actually buys you is the decision list and the evidence.

What you get

**Features**

• Google Play Billing Library **9.1.0** client module (`android/billing`, Kotlin, an Android

library you drop into an existing app): product query on the v9 `QueryProductDetailsResult`

shape, purchase flow with a stable `obfuscatedAccountId`, `PurchasesUpdatedListener`,

`queryPurchasesAsync` on every foreground, subscription upgrade/downgrade via the current

replacement-mode API, and auto-reconnection

• Server-authoritative entitlement service (Node 24.18.1, `node:sqlite`, **one** production

dependency): authenticated RTDN intake, Play Developer API verification, a nine-state

subscription entitlement matrix, the three-day acknowledgement window handled server-side,

and a reconciliation job for everything RTDN drops

• Offline-provable Pub/Sub push authentication: OIDC RS256 token verification against a JWKS,

with `alg` pinning, issuer/audience/service-account/expiry checks, and a locally minted

attacker key so "signed by the wrong key" is a real rejection in the test suite

• Delivery-pathology handling as code, not comments: duplicate deliveries, out-of-order

deliveries, and late deliveries that must not regress newer state

• Play Console review preflight: the statically checkable submission blockers as a script, plus

a short human checklist for the ones that need a person

• One-command acceptance: `verify.sh`, 12 checks, no Google account required

**Screens / surfaces**

• Server endpoints: `POST /rtdn` (Pub/Sub push target), `POST /link` (client purchase relay),

`GET /entitlements/:appAccountId`, `GET /healthz`

• Android: a library module, not a UI. The purchase flow is Google's own Play billing sheet;

your paywall stays yours. `EntitlementState` is what your UI observes — a cache of server

truth, never a source of it

• shadcn/Tailwind is n/a for this pack: there is no web UI surface to design

**Build budget**

• Expected: **2–3 sessions on a $20/mo plan** (Claude Pro or equivalent — Pro's binding

constraint is prompt volume inside its 5-hour rolling window and weekly cap, not raw tokens;

Anthropic doesn't publish an exact token-per-window figure, so treat the session count as an

expectation, not a guarantee). Session 1: `prompts/01-build` (three parallel lanes, tasks

routed cheap/standard per TASKS.md; two tasks need the `capable` tier — the push-token

verifier and the entitlement/acknowledgement state machine). Session 2: `prompts/02-verify`

fix loop. Optional session 3: `prompts/03-golive` once your Play Console side exists.

• Plan on **~800k fresh tokens** (input + output) for one build pass. **That number is an

estimate, not a measurement** — this pack is `status: draft` and has no receipt yet. It is

anchored on `appstore-machinery`'s measured 730k for a comparably shaped pack and adjusted up

for one extra task and a second capable-tier task. When the harness runs this pack, the

receipt replaces it with a measured figure and a measured per-run dollar cost.

android-kotlin-node versions lock