Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, this project adheres to Semantic Versioning, commits follow Conventional Commits, and this changelog is generated by Structured Changelog.

Unreleased

v0.1.0 - 2026-10-28

Highlights

  • A billing runtime that reads a product's pricing and packaging from a pricing spec: it computes the products and prices a provider should hold, starts checkout and the customer portal, and turns a paid subscription into an entitlement through ports the host supplies
  • Fails at startup when billing is half configured, and runs every account on the spec's default plan when no provider is configured
  • A Stripe adapter for customers, plan and one-time checkout, the customer portal, Connect Express sellers with destination-charge sales, catalog sync with a dry run, and webhook verification
  • A lifecycle that decides entitlement from the provider's current state when Lifecycle.Provider is set, so replays and the order webhooks arrive in do not matter, serializes concurrent handling per account when Lifecycle.Locker is set, and applies refunds, seller account changes and disputes through sinks

Added

  • Billing port and Disabled free mode: with no provider every account is on the spec's default plan and anything that needs a provider reports it is not configured (260f1f3)
  • CheckStartup requires a valid spec, a webhook secret (two with a marketplace) and something to sell when a provider key is set, and names what is missing without ever printing a secret (4746a52)
  • ProviderPlanFor computes the products and prices a provider should hold, with stable lookup keys and a payforge_app tag so several products can share one account (639c2ff)
  • Product checkout, customers, errors and the subscription grant rule: active, trialing and past_due grant, and a price the spec does not have never grants (f7e8b64)
  • stripe adapter with customers keyed to the host's subject, plan and one-time checkout, and customer portal sessions; idempotency keys cover every parameter Stripe compares (bfeb668)
  • Catalog sync to a Stripe account by lookup key, with a dry run; it never deletes and a changed amount creates a new price and moves the key to it (e0e7fd7)
  • Webhook verification against several signing secrets, reduced to a normalized event; Webhook.Mode is required and events of the other mode are ignored (fa5e779)
  • Store and entitlement-sink ports with in-memory implementations (a80eb82)
  • Lifecycle.Handle turns subscription events into entitlements from the provider's current state, idempotent by event, skipping connected-account events and keeping events for unknown customers retryable (a1bebb2)
  • Connect Express accounts, onboarding links, account state and destination-charge sales with a platform fee; a sale refuses a seller that cannot take charges or that this app did not create (3bed862)
  • Refunds of payforge sales and seller account changes applied through optional sale and seller sinks (21660f3)
  • Checkout, portal and onboarding URLs must be https and are limited to AllowedURLHosts; with a test-mode key localhost, 127.0.0.1 and ::1 are also accepted, over http too, and with a live key they are refused, including in the list (acbf1fd)
  • Prices without a lookup key grant a plan only when listed in Lifecycle.LegacyPrices; metadata never names a plan (d83ca60)
  • Disputes and failed delayed payments become events, and disputes reach an optional Lifecycle.Disputes sink; the lifecycle ignores a failed delayed payment (EventCheckoutFailed), which the host handles itself (c864306)
  • Optional Locker port serializes the lifecycle and plan checkout per account, with MemoryLocker for a single process; a new plan checkout expires the subject's other open ones (4aa3c1f)
  • Examples of a catalog sync, a pricing page, a webhook endpoint and limit checks, each run by a test without a Stripe account (d23e5a1)

Documentation

  • Specifications: product and technical requirements, plan and roadmap (c97484c)
  • A user guide covering the catalog, checkout and the portal, webhooks, the lifecycle, marketplaces and known limitations, built as an MkDocs site (1649479)

Tests

  • Tests for startup checks, free mode, lookup keys and the provider plan, with golden files (7f5101a)
  • The Stripe adapter, sync, webhooks and Connect tested against a fake Stripe API that keeps state and enforces idempotency keys (21ae82c)
  • payforgetest conformance suites for stores and sinks, and lifecycle tests for replays, late events, unknown prices and failures (778c12a)
  • An opt-in live test against Stripe's test mode that runs only with a test-mode key (dc42f7b)

Infrastructure

  • Module, license, lint configuration and CI workflows (2d79f83)