@opengroundplan/core 0.1.1

package/catalog/sources/payments-billing.yaml

@@ -0,0 +1,553 @@
+# payments-billing.yaml
+#
+# Category: payments-billing
+# Research date: 2026-07-18
+#
+# VERIFICATION NOTES
+# Adversarial re-verification pass: 2026-07-18. Every entry re-checked against primary sources.
+#
+# LICENSE GATE
+# - METHOD/LIMITATION: the unauthenticated GitHub REST API was rate-limited to 0/60 for this
+#   entire session (no token available in the environment), so `license.spdx_id` could not be
+#   read from the JSON endpoint on this pass either. The brief's hard rule permits the LICENSE
+#   file as the alternative primary source, and that is what was used — arguably stronger, since
+#   spdx_id is merely GitHub's licensee-derived reading of the same file. Archived/disabled
+#   status came from the repo page's "Public archive" banner; this method was validated with
+#   positive controls (it correctly flagged vercel/nextjs-subscription-payments and
+#   medusajs/nextjs-starter-medusa as archived), so a negative result is meaningful, not a
+#   silent false negative. Star counts came from the repo-page counter, dates from the
+#   commit atom feed. Re-confirm spdx_id from the API on any future pass that has a token.
+# - Gated on the VERBATIM TEXT of each repo's LICENSE file fetched from raw.githubusercontent.com
+#   at the repo's actual default branch (note: killbill=master, medusa=develop, autumn=dev,
+#   cashier-stripe=16.x — fetching `main` for these would 404 or read the wrong tree).
+#   All 15 root licenses re-read and confirmed. No SPDX id below is a guess.
+# - MONOREPO SUB-LICENSE CHECK: full file trees enumerated (`git clone --filter=blob:none` +
+#   `ls-tree -r`) for every multi-package repo — polar, openmeter, autumn, medusa, hyperswitch,
+#   open-saas — specifically hunting for an EE/commercial directory under a permissive root.
+#   Every sub-LICENSE found is permissive: polar clients/apps/app=Apache-2.0;
+#   openmeter collector/benthos/internal=MIT (Ashley Jeffs 2020 — predates the Redpanda
+#   relicensing, so it is NOT the source-available Connect license) and
+#   api/spec/packages/aip-client-javascript=Apache-2.0; autumn packages/atmn=MIT,
+#   packages/autumn-js + packages/gateway=MIT (Recase Inc.); medusa packages/design-system/*=MIT.
+#   No BUSL, SSPL, or AGPL hiding in any subtree.
+# - AGPL-3.0 projects (Lago, Flexprice, Meteroid) are EXCLUDED, not merely flagged: copying from
+#   them would impose AGPL terms on every repo Groundplan generates. AGPL text re-confirmed verbatim.
+# - Apache-2.0 and BSD-3-Clause entries are vendorable but REQUIRE the NOTICE/copyright line to be
+#   carried into any adapted file.
+#
+# METRICS
+# - Stars, last-commit dates, and archived status re-read from the repo page star counter and
+#   /commits/HEAD.atom feed. All 15 entries matched the recorded values exactly (0 star drift,
+#   0 date drift). All 15 URLs return 200 with no redirect; none is archived or disabled.
+#
+# CONTENT (this is where the defects were)
+# - whatToBorrow claims were treated as falsifiable and spot-checked against real file trees.
+#   Confirmed accurate: saas-starter lib/payments/* + .env.example contract + db:migrate/db:seed;
+#   open-saas template/app/src/payment/ decomposition (all 9 cited files exist);
+#   killbill pom.xml modules (catalog, subscription, entitlement, invoice, payment, usage,
+#   overdue, junction, currency, account, tenant — all present); polar server/polar/benefit/grant/;
+#   openmeter openmeter/credit/{balance,grant}; medusa packages/modules/payment/src/services/
+#   payment-provider.ts + 26 workflows-sdk files; hyperswitch 325 connector implementations;
+#   dj-stripe WebhookEventTrigger; spatie webhook_calls/ProcessWebhookJob; cashier Billable.php +
+#   WebhookController.php; t3 syncStripeDataToKV; autumn check()/track()/attach().
+# - TWO entries were materially wrong and have been corrected or dropped — see droppedCandidates
+#   for ixartz/SaaS-Boilerplate (claimed Stripe integration that does not exist in the repo), and
+#   the stripe-samples/subscription-use-cases entry for the removed per-seat claim.
+#   boxyhq/saas-starter-kit was corrected: its audit log, SAML/SCIM and webhook queue are
+#   third-party services (retraced, saml-jackson, svix), not vendorable homegrown code.
+#
+# LAYER ID NORMALIZATION
+# - Inbound webhook receipt was split across two namespaces (`payments-webhook-receiver` vs
+#   `webhooks-*`); unified to `webhooks-inbound-receiver`. Seat billing was split between
+#   `billing-team-seats` and `billing-per-seat`; unified to `billing-per-seat` (the team/org
+#   linkage is already carried by `billing-org-scoped`). boxyhq's `webhooks-queue-retry` was
+#   retargeted to `webhooks-outbound-delivery` to match polar, since its queue is outbound-only.
+#   `billing-subscription-state` was removed from nextjs/saas-starter: that entry's own
+#   whatToAvoid documents its state handling as silently desyncing, so it must not be the source
+#   for that layer — `billing-state-sync` (t3dotgg, dj-stripe) owns it instead.
+
+category: payments-billing
+
+sources:
+  - name: nextjs/saas-starter
+    url: https://github.com/nextjs/saas-starter
+    stars: 15969
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2025-12-11"
+    complexity: standard
+    stack: Next.js App Router, Postgres, Drizzle ORM, Stripe, shadcn/ui, TypeScript
+    whatToBorrow: >-
+      The canonical minimal Stripe-on-Next.js seam, and small enough to read end to end.
+      Verified layout: `lib/payments/stripe.ts` (Stripe client + checkout/portal session
+      creation) and `lib/payments/actions.ts` (server actions that call it), with the webhook
+      landing at `app/api/stripe/webhook/route.ts`. Borrow the split of "create session" from
+      "react to webhook", the Drizzle schema columns that cache `stripeCustomerId`,
+      `stripeSubscriptionId`, `stripeProductId` and `planName` on the team row, the
+      `drizzle.config.ts` + `pnpm db:migrate`/`db:seed` workflow, and the `.env.example`
+      contract (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`) plus the documented
+      `stripe listen --forward-to localhost:3000/api/stripe/webhook` local loop.
+    whatToAvoid: >-
+      Billing is attached to a `teams` table, so single-user products inherit a team concept they
+      do not need. Subscription state is denormalized onto that row with no event log, so a
+      dropped or out-of-order webhook silently desyncs entitlements — pair it with the
+      sync-from-Stripe pattern in t3dotgg/stripe-recommendations. Hand-rolled JWT-in-cookie auth
+      is demo-grade; swap for a real auth layer. Slowest-moving repo in this list (last commit
+      Dec 2025) — still current, but not actively iterated.
+    proposedLayerIds:
+      - payments-stripe
+      - payments-stripe-checkout
+      - payments-stripe-webhooks
+      - db-postgres-drizzle
+      - framework-nextjs-app-router
+
+  - name: wasp-lang/open-saas
+    url: https://github.com/wasp-lang/open-saas
+    stars: 14941
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: professional
+    stack: Wasp framework, React, Node.js, Prisma, Stripe + Polar + Lemon Squeezy
+    whatToBorrow: >-
+      The single best multi-provider abstraction in this category, and the reason to study it is
+      one file. Verified layout under `template/app/src/payment/`: `paymentProcessor.ts` defines
+      the provider interface, with `stripe/`, `polar/` and `lemonSqueezy/` as swappable
+      implementations behind it; `webhook.ts` is the shared inbound handler;
+      `paymentProcessorPlans.ts` and `plans.ts` separate the plan catalog from provider price ids;
+      `operations.ts` holds the server actions; `PricingPage.tsx` and `CheckoutResultPage.tsx`
+      cover the UI ends; `env.ts` centralizes the credential contract. Lift `paymentProcessor.ts`
+      wholesale as the shape of a `payments-provider-abstraction` layer — it is exactly the seam
+      a scaffolding tool needs to make Stripe-vs-Polar a build-time choice.
+    whatToAvoid: >-
+      Everything is expressed through Wasp's DSL (`payment.wasp.ts`, Wasp `operations`), so the
+      code is not directly portable to a plain Next.js or Express target — port the interface and
+      the file decomposition, not the source. Adopting the template wholesale means adopting Wasp
+      as a framework dependency, which is a real lock-in decision. Its Prisma schema and auth are
+      tightly coupled to the same DSL.
+    proposedLayerIds:
+      - payments-provider-abstraction
+      - payments-stripe
+      - payments-polar
+      - payments-lemon-squeezy
+      - webhooks-inbound-receiver
+      - billing-plan-catalog
+
+  - name: boxyhq/saas-starter-kit
+    url: https://github.com/boxyhq/saas-starter-kit
+    stars: 4869
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-05-08"
+    complexity: enterprise
+    stack: Next.js, TypeScript, Prisma, Postgres, NextAuth, Stripe, SAML Jackson
+    whatToBorrow: >-
+      The enterprise-procurement half of billing that consumer-grade starters omit entirely:
+      per-seat/team subscriptions tied to a `Team` + `TeamMember` model, an audit-log trail over
+      billing-relevant events (plan change, seat add/remove, cancellation), SAML SSO and SCIM
+      directory sync alongside the paid plan gate, and customer-facing outbound webhooks with
+      queued delivery and retry. Verified layout: `lib/stripe.ts` (client),
+      `pages/api/webhooks/stripe.ts` (inbound Stripe handler), `pages/api/webhooks/dsync.ts`
+      (SCIM directory-sync events), `pages/api/teams/[slug]/webhooks/` (per-team outbound
+      endpoint CRUD), `pages/teams/[slug]/audit-logs.tsx`, and `sync-stripe.js` for reconciling
+      the local plan catalog against Stripe. This is the reference to copy when the target is a
+      regulated or large-org buyer who will ask for SOC 2 evidence.
+    whatToAvoid: >-
+      Apache-2.0 requires the NOTICE and copyright header to travel with any file you vendor —
+      do not strip them. Three of the four headline enterprise features are third-party
+      dependencies, not code you can lift: SAML/SCIM is BoxyHQ's own `@boxyhq/saml-jackson`
+      (self-hosted, with a soft vendor tie), the audit log is `@retracedhq/retraced` +
+      `logs-viewer`, and the outbound webhook queue/retry is hosted `svix` — so borrow the
+      integration seams and the data model, not a homegrown implementation that is not there.
+      Note the inbound Stripe webhook is still handled inline; the queue/retry applies to
+      outbound delivery only. Heaviest dependency graph among the Next.js entries; stripping it
+      down to just billing takes real effort, so use it as an enterprise reference rather than a
+      base to fork for small products.
+    proposedLayerIds:
+      - payments-stripe
+      - billing-per-seat
+      - billing-org-scoped
+      - audit-log
+      - auth-saml-sso
+      - webhooks-outbound-delivery
+
+  - name: polarsource/polar
+    url: https://github.com/polarsource/polar
+    stars: 10067
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: professional
+    stack: Python (FastAPI) backend, TypeScript/Next.js clients, Postgres; Stripe Connect rails
+    whatToBorrow: >-
+      A complete, production merchant-of-record and entitlements system with the source open —
+      the most instructive full implementation here of the layer *above* the payment processor.
+      Monorepo splits `server/` (billing engine), `clients/`, `sdk/`, `infra/`, `terraform/`.
+      Borrow the benefit/entitlement grant model (purchase produces a durable grant, features
+      check grants rather than reading subscription status), the usage-metering ingestion and
+      credit/top-up ledger, the outbound webhook delivery design with signing and retries, and
+      the checkout-link/session data model. Also a strong reference for Stripe Connect Express
+      payouts if the product needs to pay third parties.
+    whatToAvoid: >-
+      This is a hosted commercial business, not a starter template — self-hosting the whole
+      platform is explicitly not the happy path, and running it means running its full infra.
+      Adopting Polar-as-a-service means routing revenue through their MoR at 3.4-5% + fixed fee,
+      which is a pricing and lock-in decision, not just a technical one. Python backend against
+      TypeScript clients makes selective vendoring awkward. Apache-2.0 NOTICE obligations apply.
+    proposedLayerIds:
+      - payments-polar
+      - entitlements-benefits
+      - billing-usage-metered
+      - billing-credits-ledger
+      - webhooks-outbound-delivery
+      - payments-merchant-of-record
+
+  - name: killbill/killbill
+    url: https://github.com/killbill/killbill
+    stars: 5627
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-16"
+    complexity: enterprise
+    stack: Java, JAX-RS, MySQL/Postgres, plugin architecture (OSGi)
+    whatToBorrow: >-
+      The reference domain model for subscription billing, and the value is the decomposition
+      even if you never run the Java. Verified top-level modules map one-to-one onto the concepts
+      a serious billing layer needs: `catalog` (versioned plan/price catalog with effective
+      dates), `subscription` and `entitlement` (deliberately separated — what was bought vs what
+      access it confers), `invoice`, `payment`, `usage`, `overdue` (dunning state machine),
+      `junction`, `currency`, `account`, `tenant` (multi-tenancy). Steal the catalog-versioning
+      approach for plan/price migrations and the overdue/dunning state machine — both are things
+      teams get wrong when rolling their own, and both are absent from every JS starter listed.
+    whatToAvoid: >-
+      Java/OSGi plugin architecture is heavy and will not be vendored into a JS or Python target —
+      treat it as a design reference and port concepts. Documentation assumes you are deploying a
+      billing server, and the operational footprint (server + plugins + analytics) is large.
+      Overkill for anything short of complex enterprise billing. Apache-2.0 NOTICE applies.
+    proposedLayerIds:
+      - billing-subscription-engine
+      - billing-catalog-versioned
+      - billing-invoice
+      - billing-dunning-overdue
+      - billing-usage-metered
+      - entitlements-benefits
+      - billing-multi-tenant
+
+  - name: openmeterio/openmeter
+    url: https://github.com/openmeterio/openmeter
+    stars: 2125
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18"
+    complexity: professional
+    stack: Go, ClickHouse, Kafka/Redpanda, CloudEvents; Stripe integration for invoicing
+    whatToBorrow: >-
+      The metering-and-entitlements layer for usage-based and AI/API pricing — the piece Stripe
+      Billing handles poorly at volume. Borrow the CloudEvents-shaped usage event schema
+      (idempotent event ids, so duplicate ingestion is safe by construction), the meter
+      definition model (aggregation type + group-by dimensions declared as config, not code),
+      the entitlement/balance API that answers "does this customer have quota left" cheaply, and
+      the Stripe sync that pushes computed usage onto subscription items for invoicing. The
+      idempotency-key discipline here is the single most reusable idea for any billing pipeline.
+    whatToAvoid: >-
+      Real infrastructure weight: ClickHouse plus a Kafka-compatible broker is a serious
+      operational commitment that is unjustified below meaningful event volume. Go implementation
+      limits direct code reuse in JS/Python targets. Open-core — check which capabilities sit in
+      the commercial tier before designing around them. Apache-2.0 NOTICE applies.
+    proposedLayerIds:
+      - billing-usage-metered
+      - entitlements-usage-quota
+      - events-cloudevents-ingest
+      - payments-stripe-usage-sync
+      - billing-idempotency
+
+  - name: juspay/hyperswitch
+    url: https://github.com/juspay/hyperswitch
+    stars: 43327
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: enterprise
+    stack: Rust, Postgres, Redis; multi-PSP payment orchestration
+    whatToBorrow: >-
+      The payment-orchestration tier — how to stay processor-agnostic instead of hardcoding
+      Stripe. Borrow the connector abstraction (each PSP implements a common request/response
+      trait, so adding a processor is additive), smart routing and fallback rules, automatic
+      retries on soft declines, the PCI-scope-reducing vault/tokenization boundary, unified
+      webhook normalization across PSPs into one internal event shape, and idempotency handling
+      on payment intents. The webhook-normalization layer is the concept most worth porting even
+      for single-processor products.
+    whatToAvoid: >-
+      Rust and very large — no realistic direct code reuse for a JS/Python scaffold; this is an
+      architectural reference. Genuine payment orchestration implies PCI obligations and a
+      compliance program most teams should avoid by staying on hosted Checkout. Enterprise
+      support/hosted tiers exist alongside the OSS core, so verify feature availability.
+      Apache-2.0 NOTICE applies.
+    proposedLayerIds:
+      - payments-orchestration
+      - payments-multi-psp-connector
+      - payments-routing-retry
+      - payments-vault-tokenization
+      - webhooks-normalization
+      - billing-idempotency
+
+  - name: medusajs/medusa
+    url: https://github.com/medusajs/medusa
+    stars: 35221
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: professional
+    stack: Node.js, TypeScript, Postgres, modular commerce framework
+    whatToBorrow: >-
+      The cleanest MIT-licensed provider-abstraction in a mainstream TS codebase. Its Payment
+      Module defines a payment-provider interface (authorize / capture / refund / cancel /
+      webhook-handle) that Stripe and others plug into, with payment sessions and payment
+      collections modeled explicitly — a far better base for a `payments-provider-abstraction`
+      layer than anything Stripe-specific, and unlike open-saas it is plain TypeScript with no
+      DSL to port. Also borrow the workflow/compensation pattern for multi-step checkout so a
+      failure mid-flow unwinds cleanly, and the idempotency handling on order placement.
+    whatToAvoid: >-
+      It is a commerce framework: carts, orders, inventory, fulfillment, regions and tax all come
+      along, and SaaS subscription billing is not its native use case — recurring billing is not
+      first-class. Adopting Medusa to get its payment abstraction is a large tail dependency;
+      extract the interface instead. Module architecture has churned across majors, so pin
+      versions and expect migration cost. Note `medusajs/nextjs-starter-medusa` (the storefront
+      companion) was ARCHIVED on 2026-04-23 — do not build on it.
+    proposedLayerIds:
+      - payments-provider-abstraction
+      - payments-stripe
+      - commerce-cart-checkout
+      - payments-session-model
+      - billing-idempotency
+
+  - name: stripe-samples/subscription-use-cases
+    url: https://github.com/stripe-samples/subscription-use-cases
+    stars: 902
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-05-01"
+    complexity: simple
+    stack: Polyglot — Node, Python, Ruby, PHP, Java, Go, .NET server implementations
+    whatToBorrow: >-
+      Stripe's own first-party reference for subscription billing, each shape an isolated minimal
+      app. Verified top-level samples: `fixed-price-subscriptions`, `usage-based-subscriptions`
+      and `usage-based-subscriptions-legacy` (the pre-meters billing API, kept for migration
+      reference) — note there is NO standalone per-seat sample here; per-seat is expressed as
+      quantity on a fixed-price subscription, and laravel/cashier-stripe is the better source for
+      seat handling. Because every sample is
+      implemented across multiple server languages against one client, it is the ideal source for
+      language-parametric templates — the same billing flow in Node and Python and Go, already
+      written by the vendor. Borrow the trial-handling, proration-on-plan-change, and
+      `checkout.session.completed` / `customer.subscription.updated` handler skeletons, plus the
+      `stripe listen` local-development setup each sample ships.
+    whatToAvoid: >-
+      Deliberately minimal: no persistence beyond toy storage, no auth, no idempotency, no retry
+      or replay protection on webhook handlers, no reconciliation. These are teaching samples,
+      not production scaffolds — treat them as the correct API call sequence and nothing more.
+      Some language variants lag the Node one in API-version currency; check pinned versions.
+    proposedLayerIds:
+      - payments-stripe-subscriptions
+      - payments-stripe-webhooks
+      - billing-usage-metered
+      - billing-trials-proration
+
+  - name: stripe-samples/accept-a-payment
+    url: https://github.com/stripe-samples/accept-a-payment
+    stars: 836
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-05-06"
+    complexity: simple
+    stack: Polyglot server samples (Node, Python, Ruby, PHP, Java, Go, .NET) + web/mobile clients
+    whatToBorrow: >-
+      The simplest correct one-time-payment path, and the right starting point when a product
+      needs checkout without subscriptions. Covers both hosted Stripe Checkout redirect and
+      embedded Payment Element/custom-flow variants, so it is the natural source for a
+      `payments-one-time` layer with a hosted-vs-embedded toggle. Borrow the PaymentIntent
+      lifecycle (create → confirm → handle requires_action/3DS) and the client-secret handling
+      convention, which are easy to get subtly wrong.
+    whatToAvoid: >-
+      Same caveats as the sibling samples repo: no database, no auth, no idempotency keys, and
+      webhook handlers that verify the signature but do nothing durable. Fulfillment logic is
+      stubbed, which is precisely the part that matters in production. Do not ship the embedded
+      variants without re-reading current SCA/3DS guidance.
+    proposedLayerIds:
+      - payments-one-time
+      - payments-stripe-checkout
+      - payments-stripe-elements
+      - payments-stripe-webhooks
+
+  - name: laravel/cashier-stripe
+    url: https://github.com/laravel/cashier-stripe
+    stars: 2537
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-06-24"
+    complexity: standard
+    stack: PHP, Laravel, Stripe
+    whatToBorrow: >-
+      The most mature framework-native billing abstraction in any ecosystem, and the best model
+      for what a good billing API *feels* like. Borrow the `Billable` trait design (a model gains
+      `newSubscription()`, `subscribed()`, `subscribedToPrice()`, `cancelAtPeriodEnd()`), the
+      subscription + subscription_items tables with quantity handling for seats, the
+      `WebhookController` that maps Stripe events to overridable handler methods, the
+      grace-period/trial semantics, and the invoice-PDF generation. Even for a TypeScript target,
+      this is the API surface worth imitating.
+    whatToAvoid: >-
+      Only meaningful inside Laravel — the value for other stacks is the interface design, not
+      the code. Version-locked to specific Stripe API versions, so upgrades are coordinated
+      events. Its conventions assume Eloquent models and Laravel's queue/event system, so the
+      webhook handling does not lift out cleanly.
+    proposedLayerIds:
+      - payments-stripe
+      - framework-laravel
+      - billing-subscription-model
+      - billing-per-seat
+      - webhooks-inbound-receiver
+      - billing-invoice
+
+  - name: dj-stripe/dj-stripe
+    url: https://github.com/dj-stripe/dj-stripe
+    stars: 1786
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-02"
+    complexity: standard
+    stack: Python, Django, Postgres, Stripe
+    whatToBorrow: >-
+      The strongest example of the "mirror Stripe into your own database" strategy: dj-stripe
+      defines Django models for Customer, Subscription, Product, Price, Invoice, Event and keeps
+      them synced from webhooks, so application code queries local tables instead of calling the
+      Stripe API on every request. Borrow the model schema (a ready-made ERD for billing state),
+      the idempotent event-processing table that records every received Stripe event id before
+      acting on it — the correct fix for duplicate and out-of-order webhook delivery — and the
+      backfill/resync management commands for recovering from missed events.
+    whatToAvoid: >-
+      Mirroring the full Stripe object graph is more schema than most products need, and
+      migrations across dj-stripe majors have historically been painful. Tightly coupled to the
+      Django ORM and admin. Tracks Stripe API versions on its own cadence, so you inherit its
+      upgrade timeline rather than Stripe's.
+    proposedLayerIds:
+      - payments-stripe
+      - framework-django
+      - billing-webhook-event-log
+      - billing-state-sync
+      - billing-idempotency
+      - db-postgres
+
+  - name: useautumn/autumn
+    url: https://github.com/useautumn/autumn
+    stars: 2617
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: professional
+    stack: TypeScript, Node, Postgres; sits on top of Stripe
+    whatToBorrow: >-
+      Purpose-built for the layer most teams hand-roll badly: pricing model and feature
+      entitlements on top of Stripe. Borrow the declarative product/feature/pricing definition
+      (plans and their limits declared as data, so adding a tier is config not code), the
+      `check`/`track` entitlement API shape (ask "can this customer use feature X" and record
+      consumption in one place), credit-balance and top-up handling, and its treatment of
+      upgrades/downgrades/proration as a first-class operation instead of ad-hoc Stripe calls.
+      The clearest modern TypeScript answer to "where does entitlement logic live".
+    whatToAvoid: >-
+      Young project relative to the others — smaller community, API surface still moving, so pin
+      hard and expect churn. Open-core with a hosted commercial offering; confirm which features
+      are in the OSS tier before designing around them. Still fundamentally a wrapper over
+      Stripe, so it inherits Stripe's constraints rather than abstracting the processor.
+      Apache-2.0 NOTICE applies.
+    proposedLayerIds:
+      - entitlements-feature-gating
+      - billing-plan-catalog
+      - billing-credits-ledger
+      - billing-upgrade-downgrade-proration
+      - payments-stripe
+
+  - name: t3dotgg/stripe-recommendations
+    url: https://github.com/t3dotgg/stripe-recommendations
+    stars: 6376
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2025-02-07"
+    complexity: simple
+    stack: Documentation + TypeScript snippets, KV/Redis-oriented
+    whatToBorrow: >-
+      A short, opinionated writeup of the specific Stripe failure modes that bite in production,
+      and the highest value-per-line item in this list. The central pattern worth encoding as a
+      layer: never trust individual webhook event payloads to mutate state incrementally —
+      instead have every event (and the post-checkout success redirect) call one idempotent
+      `syncStripeDataToKV(customerId)` function that refetches the customer's authoritative state
+      from Stripe and overwrites the local cache. That single-writer design eliminates the
+      out-of-order and duplicate-delivery races that nextjs/saas-starter and most tutorials leave
+      open. Also borrow its eager customer-creation-before-checkout rule and its explicit list of
+      events worth subscribing to.
+    whatToAvoid: >-
+      Prose and snippets, not a runnable app — there is nothing to fork. It is one engineer's
+      opinion, not Stripe documentation, and some advice is specific to a KV/Redis-cached
+      architecture that does not map cleanly onto a relational entitlement model. Effectively
+      dormant (last touched Feb 2025), so it predates newer Stripe APIs; validate against current
+      docs before encoding any of it.
+    proposedLayerIds:
+      - payments-stripe-webhooks
+      - billing-state-sync
+      - billing-idempotency
+      - payments-stripe-checkout
+
+  - name: spatie/laravel-webhook-client
+    url: https://github.com/spatie/laravel-webhook-client
+    stars: 1190
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-06-26"
+    complexity: simple
+    stack: PHP, Laravel; provider-agnostic inbound webhook receiver
+    whatToBorrow: >-
+      A tight, single-concern implementation of *receiving webhooks safely*, decoupled from any
+      payment provider — useful precisely because it isolates the pattern. Borrow the pipeline
+      shape: verify signature → persist the raw payload to a `webhook_calls` table → dispatch a
+      queued job to process it → respond 200 immediately. That store-then-process-async ordering
+      is what keeps a slow handler from causing provider-side retries and duplicate processing,
+      and it generalizes to Stripe, Paddle, Lemon Squeezy and Polar alike. Also borrow its
+      pluggable signature-validator interface and its profile-per-provider config.
+    whatToAvoid: >-
+      Laravel-specific and small in scope: it gives you safe receipt, not billing semantics —
+      you still have to write everything that happens after the job dequeues. Depends on a
+      working queue worker, so it is the wrong choice for a deployment target without one.
+      Nothing payment-aware in it, which is the point, but do not mistake it for a billing layer.
+    proposedLayerIds:
+      - webhooks-inbound-receiver
+      - webhooks-signature-verify
+      - webhooks-queue-retry
+      - billing-webhook-event-log
+      - framework-laravel
+
+droppedCandidates:
+  - "ixartz/SaaS-Boilerplate — MIT, 7,291 stars, active (2026-07-02): license and metrics all check out, but DROPPED IN VERIFICATION because its billing content was substantially misdescribed. The repo contains NO Stripe integration whatsoever — no `stripe` dependency in package.json, and zero files matching stripe/webhook/checkout/portal across the whole tree. The prior entry's claims of a customer-portal redirect flow, a subscription-tier permission gate, and org-scoped subscription records are not backed by any code. What actually exists is a static typed plan-limits catalog (`src/utils/PricingPlans.ts` + `src/types/Subscription.ts`, free/premium/enterprise with teamMember/website/storage/transfer limits) and presentational i18n pricing UI (`src/features/billing/PricingCard.tsx`, `PricingFeatureList.tsx`, `src/templates/Pricing.tsx`). Paid plans carry a `lookupKey`, implying billing is expected to be wired through Clerk Billing rather than direct Stripe. Its only distinctive contribution — localized/multi-currency pricing presentation — does not justify a payments-billing source slot, and `billing-plan-catalog` is better sourced from wasp-lang/open-saas and useautumn/autumn. Reconsider under a frontend/pricing-UI category."
+  - "getlago/lago — AGPL-3.0 (verified verbatim: 'GNU AFFERO GENERAL PUBLIC LICENSE Version 3'). 10,227 stars, active (2026-07-16), technically the strongest OSS metering/billing engine, but EXCLUDED: copying would impose AGPL on generated repos. Safe to run as a separate self-hosted service; never vendor its code."
+  - "flexprice/flexprice — AGPL-3.0 (verified verbatim). 3,594 stars, active (2026-07-18). Excluded on license."
+  - "meteroid-oss/meteroid — AGPL-3.0 (verified verbatim). 1,153 stars, active (2026-07-09). Excluded on license."
+  - "vercel/nextjs-subscription-payments — MIT, 7,722 stars, but ARCHIVED 2025-01-23 and explicitly sunset by its owner in favor of nextjs/saas-starter. Its Supabase webhook-sync pattern was long the canonical reference; the successor is listed above instead."
+  - "medusajs/nextjs-starter-medusa — MIT, 2,789 stars, but ARCHIVED 2026-04-23. Do not build on it."
+  - "lmsqueezy/lemonsqueezy.js — MIT and permissive, but last commit 2024-11-05, roughly 20 months stale as of this research date. Lemon Squeezy coverage is better taken from wasp-lang/open-saas's live lemonSqueezy/ adapter."
+  - "PaddleHQ/paddle-node-sdk — Apache-2.0 and maintained (2026-06-11), but only 102 stars and it is a thin SDK, not adaptable starter material. Use as the dependency for a payments-paddle layer; there is no meaningful Paddle *starter* in the OSS ecosystem, which is a genuine gap."
+  - "saleor/saleor — BSD-3-Clause (verified verbatim), 23,109 stars, active (2026-07-16). Legitimate and vendorable, but its payment abstraction overlaps medusajs/medusa while carrying a heavier Python/GraphQL commerce stack; Medusa is the better-fitting source for the same layers."
+  - "stripe/stripe-node (MIT, 4,475 stars) and stripe/stripe-cli (Apache-2.0, 2,120 stars) — both current and permissive, but they are the SDK and the local dev tool, not adaptable templates. stripe-cli should still be referenced by any Stripe layer for the 'stripe listen' local webhook loop."
+  - "apptension/saas-boilerplate — MIT, 2,934 stars, last commit 2026-04-13. Solid Django+React+AWS stack with a superadmin refund panel, but its billing is entangled with a heavy AWS CDK deployment story that does not decompose into portable layers."
+  - "better-auth/better-auth — MIT, 29,222 stars, very active (2026-07-18). Ships a Stripe plugin, but it is an auth library first; catalog it under the auth category and reference its Stripe plugin from the billing layers."