@ssheleg/sheleg-dev 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ All notable changes to this project are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## v0.5.0 — 2026-08-14
+
+Two gaps found by reading a web2app funnel guide against the pack. Both are about
+the same seam: the payment layer is where a funnel's money and its measurement
+actually live, and both skills were treating it as somebody else's concern.
+
+### Added
+
+- **`stripe-billing` → `references/provider-concentration.md`.** The skill covered
+  dunning *inside* Stripe and never dependence *on* Stripe. The new reference is
+  about the seam rather than about adding a second provider: the entitlement keyed
+  to your own user id with provider ids as fields, the customer identity resolved
+  before checkout, and the reconciliation job as the only number in the system
+  that is not your own telemetry. `SKILL.md` → **Reconciliation** already excluded
+  "rows that were never Stripe's", which is that seam half-built and was never
+  named as one.
+
+  It also declines the obvious answer: a generic `PaymentProvider` interface
+  written against one provider encodes that provider's model and gets rewritten
+  for the second one anyway. The seam is in the data, not in the code shape.
+
+  **Automatic card updates are documented with their two limits**, both taken from
+  Stripe's own text rather than from recall: coverage varies by country, and Stripe
+  states it is **not possible to identify which cards support it** — so any plan
+  that assumes a reissue will be caught has an unmeasurable branch. Handle
+  `payment_method.automatically_updated` and `payment_method.updated`, write the
+  new expiry and last four to your own records, and review anything keyed on
+  `fingerprint`, which moves when the card number does.
+
+  And the distinction the pack had no field for: a subscription that ended because
+  someone chose to leave, versus one that ended because a bank reissued a number.
+  A single `canceled` status for both is how a recoverable failure gets a farewell
+  email.
+
+### Changed
+
+- **`ad-tracking` now says where a purchase event comes from.** Deduplication by
+  `event_id` was already covered; what was missing is the reason the server side
+  is not optional. Every other event on the list is something a person did in a
+  tab. A purchase is the outcome of a charge that succeeded inside a payment
+  system, and the only thing that knows it succeeded is the provider's webhook —
+  so firing it from the thank-you page fires it from the one place with no idea
+  whether the charge cleared, which is why a browser-only purchase count has an
+  event for every session that reached the page and a refund for none of them.
+
+  The ordering that follows: the webhook handler is the source of truth and sends
+  the server-side conversion; the browser event stays for the signals only it
+  carries and is subordinate on conflict; and everything the browser loses, it
+  loses closest to the money, so the bias is downward by an amount that cannot be
+  measured from inside the browser. Reconcile against the provider's count of
+  succeeded charges, which is the only external check on this event that is not
+  itself telemetry.
+
+Both `SKILL.md` bodies stay inside the 500-line progressive-disclosure budget:
+`stripe-billing` went to 502 lines when this was written inline, which is what
+moved the full treatment into a reference and left a pointer behind.
+
 ## v0.4.3 — 2026-08-14
 
 A red `validate` could not stop a publish, and this repository proved it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/sheleg-dev",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Six integration skills for the layer a product reaches once it has users: Stripe subscription billing, crypto payments, ad and conversion tracking under Consent Mode v2, Google sign-in and the wider Google auth surface, and Core Web Vitals. This package is the installer CLI.",
   "bin": {
     "sheleg-dev": "bin/sheleg-dev.js"
@@ -41,5 +41,8 @@
     "claude-code",
     "cursor",
     "skill"
-  ]
+  ],
+  "scripts": {
+    "test": "python3 test/validate.py"
+  }
 }

package/plugins/sheleg-dev/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "sheleg-dev",
   "displayName": "Sheleg Dev",
   "description": "The integration layer a product needs once it has users: Stripe subscription billing reconciled into your own database, crypto payments that survive over-payment and duplicate webhooks, ad and conversion tracking under Consent Mode v2, Google sign-in with the account-linking guards, the wider Google auth surface, and Core Web Vitals work that moves the score.",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/sheleg-dev/skills/ad-tracking/SKILL.md

@@ -319,6 +319,36 @@ from both the browser and the server (Conversions API, server-side GA4) must
 carry the SAME `event_id` / `transaction_id`, or both are counted. Test it by
 reloading the thank-you page: a purchase that increments twice is a
 deduplication bug, not a tracking success.
+
+**A purchase is not a browser event, and that decides where it comes from.**
+Every other event on the list is something a person did in a tab, so the browser
+is its natural source. A purchase is the outcome of a charge that succeeded
+inside a payment system, and the only thing that knows it succeeded is the
+provider's webhook. Firing it from the thank-you page means firing it from the
+one place that has no idea whether the charge cleared — which is why a purchase
+event exists for every session that reached the page and a refund exists for
+none of them.
+
+The consequence is an ordering, not a preference:
+
+1. **The webhook handler is the source of truth for the purchase.** It writes the
+   entitlement, and the same handler sends the server-side conversion. If the
+   handler is where the money is recorded, it is where the event belongs.
+2. **The browser event stays, and it stays subordinate.** Keep it for the
+   attribution signals only the browser carries (click ids, the consent state,
+   the session), give it the `event_id` the server will reuse, and treat the
+   server as authoritative when they disagree.
+3. **Everything the browser loses, it loses closest to the money.** Blockers, a
+   mobile browser terminating a tab on redirect, a payment provider's hosted page
+   ending the session before the return leg — each of them removes the *last*
+   step preferentially, so the browser-only purchase count is biased low by an
+   amount you cannot measure from inside the browser.
+
+Reconcile against the provider rather than the analytics dashboard: the count of
+succeeded charges in a period is a number the payment system will give you
+exactly, and it is the only external check on this event that is not itself
+telemetry. See `stripe-billing` → **Depending on one provider** for what else
+that reconciliation surfaces.
 ## Content Security Policy
 
 Read `references/performance-security.md` → **Content Security Policy** for the

package/plugins/sheleg-dev/skills/stripe-billing/SKILL.md

@@ -43,6 +43,7 @@ Deep material, loaded on demand:
 | [`references/subscription-lifecycle.md`](references/subscription-lifecycle.md) | implementing checkout, verify, renewal, seats, plan change, trials, cancellation, clawback |
 | [`references/price-integrity.md`](references/price-integrity.md) | pricing lives in more than one file, or an advertised price must be proved against Stripe |
 | [`references/testing-and-local-dev.md`](references/testing-and-local-dev.md) | local webhooks, fixtures, mocks, and a suite that would actually catch a money defect |
+| [`references/provider-concentration.md`](references/provider-concentration.md) | growing revenue, opening a second market, separating involuntary churn, or asking what happens if the payment account is limited |
 
 ---
 
@@ -395,6 +396,29 @@ units: convert once, at the boundary, and compare in integer cents —
 
 ---
 
+## Depending on one provider
+
+Everything above assumes Stripe is the payment system. That is a reasonable
+default and it is also a concentration: the account that runs the charges can be
+limited or closed, and there is no second route unless one was built before it
+was needed. Three things make adding a second provider cheap later and are
+nearly free now — the entitlement keyed to **your** user id with provider ids as
+fields, the customer identity resolved before checkout, and the reconciliation
+job above, which is the only number in the system that is not your own telemetry.
+
+At volume, three leaks that do not look like payment problems: approval rates
+differing by country, renewals failing on reissued cards, and a `canceled`
+status that cannot tell a decision from a bank reissue. Stripe's **automatic
+card updates** cover some of the second one, with two limits worth knowing —
+coverage varies by country and Stripe states you **cannot identify which cards
+it covers**, so handle `payment_method.automatically_updated` and
+`payment_method.updated` rather than assuming the save.
+
+Full treatment, including the involuntary-versus-voluntary table:
+[`references/provider-concentration.md`](references/provider-concentration.md).
+
+---
+
 ## Local development
 
 **Skip Stripe.** A `SKIP_BILLING=true` branch that creates an obviously fake

package/plugins/sheleg-dev/skills/stripe-billing/references/provider-concentration.md

@@ -0,0 +1,120 @@
+# Depending on one provider
+
+**Load this when** revenue is growing, when a second market is being opened, when
+involuntary churn needs separating from voluntary, or when someone asks what
+happens if the payment account is limited.
+
+Everything in `SKILL.md` assumes Stripe is the payment system. That is a
+reasonable default and it is also a concentration: the account that runs the
+charges can be limited or closed, and when it is, there is no second route unless
+one was built before it was needed. The seam that makes a second route possible
+costs almost nothing while there is one provider, and becomes a migration once
+there are two.
+
+## Contents
+
+- [Keep the seam, not the second provider](#keep-the-seam-not-the-second-provider)
+- [Three ways this costs money at volume](#three-ways-this-costs-money-at-volume)
+- [Automatic card updates, and what they do not tell you](#automatic-card-updates-and-what-they-do-not-tell-you)
+- [Involuntary is not voluntary](#involuntary-is-not-voluntary)
+- [Checklist](#checklist)
+
+## Keep the seam, not the second provider
+
+Running two providers from day one is two webhook surfaces, two reconciliations,
+two test matrices and two sets of tax obligations, for a problem most products
+never have. Adding the second one later is cheap **if** three things were true
+from the start, and expensive if they were not.
+
+- **The entitlement is yours and the charge is theirs.** Your own row, keyed to
+  your own user id, with the provider's ids as fields on it rather than as its
+  primary key. `SKILL.md` → **Reconciliation** already assumes this: its loop
+  excludes "rows that were never Stripe's" — comped, manual and other-provider
+  plans with synthetic ids. That exclusion is this seam, half-built.
+- **The customer identity is yours too.** Email or user id, resolved before
+  checkout, so a second provider can be added without re-identifying the base.
+  A provider's customer id as your only handle on a person is the migration
+  nobody budgets for.
+- **The reconciliation job is the external check.** It is the one number in the
+  system that is not telemetry: charges that succeeded, reported by the party
+  that processed them. Everything else you know about revenue is inference from
+  your own instrumentation.
+
+What this is **not**: an argument for an abstraction layer over payments. A
+generic `PaymentProvider` interface written against one provider encodes that
+provider's model and has to be rewritten for the second one anyway. The seam is
+in the data — whose id owns what — not in the code shape.
+
+## Three ways this costs money at volume
+
+None of these looks like a payments problem from inside the app.
+
+| What happens | Why it is invisible | Where to look |
+|---|---|---|
+| Approval rates differ by country, and some markets are not served at all | An unserved market is obvious. A market with a poor approval rate is not: a declined charge and a customer who changed their mind produce the same empty result in the funnel | Decline codes grouped by country, measured against **attempts** rather than against successes |
+| Renewals fail on cards that expired, were reissued, or were blocked | The subscription ends and nobody decided to end it, so it lands in churn beside voluntary cancellations | `invoice.payment_failed` and the dunning path, kept separate from the `customer.subscription.deleted` that came from your own UI |
+| A replaced card silently keeps working, or silently does not | See the next section: the mechanism exists, its coverage varies by country, and Stripe states you cannot tell which cards it covers | `payment_method.automatically_updated` and `payment_method.updated` |
+
+The measurement that makes the first row actionable is the denominator. Approval
+rate is successes over *attempts*, and a dashboard that reports successes over
+successes reports 100% in every market.
+
+## Automatic card updates, and what they do not tell you
+
+Stripe works with the card networks and **automatically** attempts to update
+saved card details when a customer's card is replaced, so a saved payment method
+can keep working after an expiry or a reissue. There is nothing to switch on.
+
+Two limits, both stated by Stripe and both load-bearing:
+
+- Support is **wide in the United States** across American Express, Visa,
+  Mastercard and Discover issued there, and **varies by country** elsewhere,
+  because it needs the issuer to participate.
+- It is **not possible to identify which cards support it**. So you cannot
+  compute how much of your subscription base is protected, and any plan that
+  assumes the mechanism will catch a reissue is a plan with an unmeasurable
+  branch.
+
+What to do rather than assume:
+
+- Listen for **`payment_method.automatically_updated`** for network-driven
+  changes and **`payment_method.updated`** for API-driven ones.
+- Both carry the card's new expiration and last four. Write them to your own
+  records from the event, or the billing page keeps showing digits the customer
+  no longer has, and a support ticket follows a change that actually succeeded.
+- A card update that includes a new **number** changes the payment method's
+  `fingerprint`. If anything in your system keys off the fingerprint — dedup of
+  saved cards, fraud rules, "you already used this card" — that identity moves
+  under it.
+
+## Involuntary is not voluntary
+
+Stripe owns the retry schedule and the terminal state (`SKILL.md` →
+**Renewal**, **Cancellation**). What it cannot own is the difference between a
+subscription that ended because someone chose to leave and one that ended because
+a bank reissued a number.
+
+Keep them apart in your own data, because everything downstream reads it:
+
+| | Voluntary | Involuntary |
+|---|---|---|
+| Arrives as | your own cancel route, or `cancel_at_period_end` | `invoice.payment_failed` → dunning → terminal |
+| The customer's intent | stated | never expressed |
+| The right message | confirm, and say what happens to their data | tell them a payment failed and how to fix it |
+| The wrong message | — | a farewell email, which spends the relationship on a recoverable failure |
+| Counts as churn | yes | yes, and reporting it in the same number hides a fixable revenue leak |
+
+A single `canceled` status for both is the shape this failure takes. Record the
+cause, not just the outcome.
+
+## Checklist
+
+- [ ] Entitlement rows keyed to your user id, provider ids as fields
+- [ ] Customer identity (email or user id) resolved before checkout
+- [ ] Reconciliation job running, and its result compared against your own numbers
+- [ ] Decline codes grouped by country, measured against attempts
+- [ ] `payment_method.automatically_updated` and `payment_method.updated` handled,
+      and the stored last-four and expiry written from them
+- [ ] Anything keyed on `fingerprint` reviewed for the case where it changes
+- [ ] Involuntary and voluntary cancellation distinguishable in your own data
+- [ ] No farewell email on the involuntary path