lattice_stripe

# Changelog

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

This project adheres to [Semantic Versioning](https://semver.org/).

> **Publishing note:** Releases are published automatically via Release Please + Hex CI. Install: `{:lattice_stripe, "~> 2.2"}`.

> **Development status:** `2.2.1` is published. It is a compatibility-preserving quality
> patch for reliability, internal consistency, documentation truth, and release hygiene.
> The project is now in reactive maintenance; new API breadth remains adopter-driven.

## [2.2.2](https://github.com/szTheory/lattice_stripe/compare/v2.2.1...v2.2.2) (2026-08-25)


### Bug Fixes

* complete closure audit remediation ([#61](https://github.com/szTheory/lattice_stripe/issues/61)) ([4640e72](https://github.com/szTheory/lattice_stripe/commit/4640e724ff51bbad5072c88e6058a841bfce6eec))

## [2.2.1](https://github.com/szTheory/lattice_stripe/compare/v2.2.0...v2.2.1) (2026-08-25)


### Bug Fixes

* complete reader-first quality closure ([#57](https://github.com/szTheory/lattice_stripe/issues/57)) ([8586473](https://github.com/szTheory/lattice_stripe/commit/858647336962e70b9c01295f903d5efb4f0ac9b9))

## [2.2.0](https://github.com/szTheory/lattice_stripe/compare/v2.1.0...v2.2.0) (2026-08-25)

### Highlights for adopters

- Product Feature attachments complete the typed Entitlements catalog-to-access path.
- Final error responses retain ordered headers and parsed `Retry-After` evidence for
  application retry and support policy.
- Phoenix webhook body caching handles chunked request bodies without weakening signature
  verification boundaries.
- PaymentIntent-first guidance makes Charge a reconciliation surface and keeps server
  confirmation distinct from browser-side customer action.

### Features

* **66-01:** add product feature attachment create\n\n- post typed entitlement attachments to product-scoped collection\n- validate required IDs and attachment definition before transport\n ([3a17fd3](https://github.com/szTheory/lattice_stripe/commit/3a17fd3c07fa674c6f72823f933e25ffd610dbd5))
* **66-01:** complete product feature attachment surface\n\n- add retrieve list delete and streaming attachment operations\n- lock identity guards options and canonical public arities\n ([add2b75](https://github.com/szTheory/lattice_stripe/commit/add2b752ff463517f7504796c01ca829bd228405))
* **66-03:** register exact product feature discriminator ([6822573](https://github.com/szTheory/lattice_stripe/commit/682257373cd5311e5fd61ddba65a83c20fd16dbc))
* **67-01:** expose final HTTP error response metadata ([dd13608](https://github.com/szTheory/lattice_stripe/commit/dd13608d2313c69808059473b72658db124551c2))
* **67-01:** harden retry-after response evidence ([824f429](https://github.com/szTheory/lattice_stripe/commit/824f429616ef349ba15498958aec0682f81a2c40))
* **67-03:** lock CacheBodyReader public API ([9bebd70](https://github.com/szTheory/lattice_stripe/commit/9bebd704052c2b6d1b438cafba8a69f14f799325))
* **67-03:** publish CacheBodyReader contract ([353b5b9](https://github.com/szTheory/lattice_stripe/commit/353b5b9999b86ef1d953e4a6a1856aa1fe357403))
* **67-04:** publish PaymentIntent-first Charge policy\n\n- Document the permanent Charge.create/3 exclusion in canonical consumer surfaces\n- Add the confirmed PaymentIntent server example and browser/SCA distinction\n- Keep the policy constrained by section-scoped docs truth tests\n ([faa36ff](https://github.com/szTheory/lattice_stripe/commit/faa36ff75eb4909f60ea6ba416408138aae067fd))
* synchronize completed v1.10 release history ([c34b1b3](https://github.com/szTheory/lattice_stripe/commit/c34b1b33ff5bb5618c724393f7d6e0754a79c6ba))


### Bug Fixes

* **62:** complete finite status migration inventory ([6745e38](https://github.com/szTheory/lattice_stripe/commit/6745e3876c211cdd009c6e15099ff5e51d11646a))
* **62:** correct dispute evidence migration guide ([5e1c4f8](https://github.com/szTheory/lattice_stripe/commit/5e1c4f8acc6692a52eff03897ba46c419f877084))
* **62:** qualify dispute evidence file call ([09a488c](https://github.com/szTheory/lattice_stripe/commit/09a488c79b5f1e27702c338bf5856a38c3d19366))
* **62:** tighten phase scope verification ([aabd032](https://github.com/szTheory/lattice_stripe/commit/aabd032ce2b4fe686f2b396545c25ac13479a1c5))
* **62:** WR-01 bound tolerance safety contract ([c1e1409](https://github.com/szTheory/lattice_stripe/commit/c1e1409ccefdb9722f72330f6f44baea97397884))
* **66:** WR-01 correct reconciliation snapshot guidance ([e5bd47a](https://github.com/szTheory/lattice_stripe/commit/e5bd47a5da068d6c0a56c7e5e83c80b494ef7e5b))
* **67-02:** accumulate webhook body chunks\n\n- Append every Plug :more and :ok body chunk in order\n- Preserve native return tags and error passthrough\n ([df3e32c](https://github.com/szTheory/lattice_stripe/commit/df3e32cd7420af791b51ef2ae8dfcd0eab61cc91))
* **67-04:** keep Charge policy docs warning-free\n\n- Spell the permanent absent API as function plus arity without an unresolved ExDoc link\n- Preserve bounded policy assertions and rendered consumer guidance\n ([353cf17](https://github.com/szTheory/lattice_stripe/commit/353cf176152bb4056f9ae86845db37cde2c62592))
* **67-05:** flatten retry-after parsing ([aff17e2](https://github.com/szTheory/lattice_stripe/commit/aff17e2153351cafcfe0fe83c70cce1b2397774a))
* **67:** CR-01 preserve binary download retry pipeline ([81616c5](https://github.com/szTheory/lattice_stripe/commit/81616c5706e35cdd728ee12e328cc5b5a209dabe))
* **67:** CR-01 sequence retry regression responses ([59db960](https://github.com/szTheory/lattice_stripe/commit/59db960aa1145996f6491b66a859e186d8268bd9))
* **67:** CR-02 handle nullable invalid-request messages ([67b3df3](https://github.com/szTheory/lattice_stripe/commit/67b3df3231809d56b9ba73e215dadcd5ec22f2e6))
* **67:** CR-03 preserve cache-reader scope contract ([4e32362](https://github.com/szTheory/lattice_stripe/commit/4e32362940d6635b01cd780cb442250f9c3d993a))
* **67:** CR-03 scope cached webhook bodies to JSON route ([be9d105](https://github.com/szTheory/lattice_stripe/commit/be9d105e1309baaa0d0193ff8e611de080caf3fa))
* **67:** make audit isolation and flake guards executable ([ec4fd67](https://github.com/szTheory/lattice_stripe/commit/ec4fd67c909342f4fba78e9e17a93d7c7d0010a6))
* **67:** move milestone audit after phase verification ([0f188ed](https://github.com/szTheory/lattice_stripe/commit/0f188ed268247248873a3ee2a5ff1aea39577731))
* **67:** revise plans based on checker feedback ([5749cf6](https://github.com/szTheory/lattice_stripe/commit/5749cf6a333d68484cc9d9f235286427592f4012))
* **67:** WR-01 require decimal Retry-After values ([03dc3e3](https://github.com/szTheory/lattice_stripe/commit/03dc3e3b790a9da17637c75b91cc81c7f9976852))
* **67:** WR-02 retain chunked raw webhook bodies ([95f03b7](https://github.com/szTheory/lattice_stripe/commit/95f03b76125435474b92af009db829733b43827b))
* **67:** WR-03 clarify confirmation and SCA handoff ([99bdd37](https://github.com/szTheory/lattice_stripe/commit/99bdd37f93fffeeb461e70e13ba8f3dfe6b6f83e))
* **67:** WR-03 retain Charge SCA policy surface ([45cc39e](https://github.com/szTheory/lattice_stripe/commit/45cc39eab0f030c4b36f740870e08ea1c99ebdb1))
* **release:** recognize published release PRs before skipping ([#55](https://github.com/szTheory/lattice_stripe/issues/55)) ([33be042](https://github.com/szTheory/lattice_stripe/commit/33be042da12ea256082a121a1dd5d2ad2ab75a72))
* stabilize batch test and pin CI dependencies ([#52](https://github.com/szTheory/lattice_stripe/issues/52)) ([05f3f9e](https://github.com/szTheory/lattice_stripe/commit/05f3f9eb238c88d0bce6aabe714d5fc0b2c5e699))

## [2.1.0](https://github.com/szTheory/lattice_stripe/compare/v2.0.0...v2.1.0) (2026-07-29)


### Features

* **release:** sync published version prose automatically ([#48](https://github.com/szTheory/lattice_stripe/issues/48)) ([d438450](https://github.com/szTheory/lattice_stripe/commit/d43845005aa85229d9edcd9662ca6d5e494d4f4d))

## [2.0.0](https://github.com/szTheory/lattice_stripe/compare/v1.7.13...v2.0.0) (2026-07-29)


### ⚠ BREAKING CHANGES

* **65:** public test-fixture builders are renamed to the `<object>_json` convention already used by 15 of 18 fixture modules. These are called from adopters' own test suites, so the rename is free now and breaking after the 1.8.0 tag.

### Features

* **61-01:** wire default Finch pool end-to-end, relax :finch requirement ([f7fc710](https://github.com/szTheory/lattice_stripe/commit/f7fc7102458f2e3abc8a3959f6d9634971d94b27))
* **65:** zero human UAT — mechanize phase 65's verification checkpoints ([#47](https://github.com/szTheory/lattice_stripe/issues/47)) ([cd1f896](https://github.com/szTheory/lattice_stripe/commit/cd1f8968c8332cc3c120eaa38163ebf7d4c0502d))
* **entitlements:** stripe-native entitlements surface (ENT-01..05) ([#45](https://github.com/szTheory/lattice_stripe/issues/45)) ([a22e197](https://github.com/szTheory/lattice_stripe/commit/a22e197658a6a9cb02ed9da2049059c4914d54ce))


### Bug Fixes

* **61-01:** use fully-qualified Config.validate!/1 in Client typedoc ([bb39266](https://github.com/szTheory/lattice_stripe/commit/bb392664ffd9fbb8539f6c95ba237ec8b9b56728))

## [1.7.13](https://github.com/szTheory/lattice_stripe/compare/v1.7.12...v1.7.13) (2026-05-29)


### Bug Fixes

* **docs:** cut patch release for README hex.pm guide links ([326d155](https://github.com/szTheory/lattice_stripe/commit/326d1553684d26dcdc80cc3105830018e3bf678b))

## [1.7.12](https://github.com/szTheory/lattice_stripe/compare/v1.7.11...v1.7.12) (2026-05-28)


### Bug Fixes

* **docs:** graduate Connect/Webhook docs_truth clusters and close JTBD narrative ([a49a0f7](https://github.com/szTheory/lattice_stripe/commit/a49a0f7be2cb2b7fe8608f8a42e576c5a24b317b))
* **drift:** patch known_fields for Balance, BalanceTransaction, and Portal Session ([79f6baf](https://github.com/szTheory/lattice_stripe/commit/79f6baf6da130b4019de078abb87116f5b8b59db))

## [1.7.11](https://github.com/szTheory/lattice_stripe/compare/v1.7.10...v1.7.11) (2026-05-28)


### Bug Fixes

* **docs:** portal-flow sibling cluster and inter-guide .md links ([aca7b4c](https://github.com/szTheory/lattice_stripe/commit/aca7b4cd9560e6a36347acbee4046ee9bf709eac))

## [1.7.10](https://github.com/szTheory/lattice_stripe/compare/v1.7.9...v1.7.10) (2026-05-28)


### Bug Fixes

* **docs:** flatten fence helper for credo nesting limit ([3341409](https://github.com/szTheory/lattice_stripe/commit/3341409b4ee07337304a5bb285a6269fb3c14994))
* **docs:** graduate docs_truth fence and payment-flow sibling checks ([a5efa3b](https://github.com/szTheory/lattice_stripe/commit/a5efa3b89f410face85b99ae3fb5913675eaaa94))

## [1.7.9](https://github.com/szTheory/lattice_stripe/compare/v1.7.8...v1.7.9) (2026-05-28)


### Bug Fixes

* **docs:** align docs_truth with automated CHANGELOG publishing note ([4679a2a](https://github.com/szTheory/lattice_stripe/commit/4679a2a442fecb2dd185b52f3d5e58d7fddf297f))

## [1.7.8](https://github.com/szTheory/lattice_stripe/compare/v1.7.7...v1.7.8) (2026-05-28)


### Bug Fixes

* **release:** dispatch CI on main after automerge merge ([599b97a](https://github.com/szTheory/lattice_stripe/commit/599b97a9d43fe4ddd182affbb475774e11190448))

## [1.7.7](https://github.com/szTheory/lattice_stripe/compare/v1.7.6...v1.7.7) (2026-05-28)


### Bug Fixes

* **release:** dispatch Release after automerge merge ([a519a9d](https://github.com/szTheory/lattice_stripe/commit/a519a9d2ab425484659a94950b7402afb440ddfa))

## [1.7.6](https://github.com/szTheory/lattice_stripe/compare/v1.7.5...v1.7.6) (2026-05-28)


### Bug Fixes

* **release:** single CI path on release PR and retry automerge ([2c87f6a](https://github.com/szTheory/lattice_stripe/commit/2c87f6a6a2366e6073f6fcd16c42ef6abd23dbfb))

## [1.7.5](https://github.com/szTheory/lattice_stripe/compare/v1.7.4...v1.7.5) (2026-05-28)


### Bug Fixes

* **release:** automerge PAT-authored PRs and bootstrap open release CI ([783711d](https://github.com/szTheory/lattice_stripe/commit/783711d8d7317cc4bd21b0975cdea74f6897cbbe))
* **release:** use squash merge and -R in release PR automerge ([c1c1120](https://github.com/szTheory/lattice_stripe/commit/c1c11205fcb1f981f8d814d3a0bd6b392c9ff6c6))

## [1.7.4](https://github.com/szTheory/lattice_stripe/compare/v1.7.3...v1.7.4) (2026-05-28)


### Bug Fixes

* credo map_join in drift report formatting ([d5c8ee4](https://github.com/szTheory/lattice_stripe/commit/d5c8ee4fde57e84a3f2c990afb8913c8c0a9de0c))
* **release:** auto-dispatch CI and merge Release Please PRs ([284a174](https://github.com/szTheory/lattice_stripe/commit/284a1741bb9c82f76c40d8117129f386fa07f261))
* **release:** pass -R to gh workflow run in bootstrap CI job ([0fea646](https://github.com/szTheory/lattice_stripe/commit/0fea64674fc2c07a17840fdf69326733db33b541))

## [1.7.3](https://github.com/szTheory/lattice_stripe/compare/v1.7.2...v1.7.3) (2026-05-28)


### Bug Fixes

* **release:** only skip release-please on merged release PR reruns ([9c488d3](https://github.com/szTheory/lattice_stripe/commit/9c488d3cc2a73ac3a1e2e635765e03d655b9f605))
* **release:** poll for ci-gate before Hex publish ([3934bef](https://github.com/szTheory/lattice_stripe/commit/3934bef3686d30f56e7be95763522dffd6be67ad))

## [1.7.2](https://github.com/szTheory/lattice_stripe/compare/v1.7.1...v1.7.2) (2026-05-28)


### Bug Fixes

* filter .claude paths from hygiene dirty-tree check ([61da051](https://github.com/szTheory/lattice_stripe/commit/61da05169aee1f8ae1efd3fe0ab174b7a8a8becf))
* hygiene script version parse and worktree allowlist ([c80de18](https://github.com/szTheory/lattice_stripe/commit/c80de18bc4805e84bca94eccad0cd67bbd787b89))
* indent Phase moduledoc heredoc for compile warning ([c3f4786](https://github.com/szTheory/lattice_stripe/commit/c3f478652a66c4d675ec3ca79917cb280051a7af))
* relax RELEASE-TRAIN ledger grep in hygiene script ([2236e6f](https://github.com/szTheory/lattice_stripe/commit/2236e6f2ec094d93ab6b48e1994b04e59dc1457e))

## [1.7.1](https://github.com/szTheory/lattice_stripe/compare/v1.7.0...v1.7.1) (2026-05-28)

### Documentation

- **Public docs UX audit** — fixed broken guide links, corrected cheatsheet list pagination example, removed GSD/planning vocabulary from guides, standardized inter-guide `.md` links, and extended `docs_truth` regression locks.
- **Adopter-facing polish** — README scope consolidation, JTBD routing and LiveBook pointer, checkout/customer-portal/payments guide corrections, and CHANGELOG copy suitable for HexDocs readers.

_No API changes — documentation and HexDocs only._

## [1.7.0](https://github.com/szTheory/lattice_stripe/compare/v1.1.0...v1.7.0) (2026-05-27)

### Highlights

This release publishes **1.7.0** to Hex — the first package since **1.1.0**, bundling v1.4 adoption closure, v1.5 thin-event webhooks, v1.6 Tax, and v1.7 Charge expansion plus operator playbooks. Adopters on `~> 1.1` resolve to **1.7.0**.

v1.x scope and maintenance posture: see README and [User Flows & JTBD](guides/user-flows-and-jtbd.md).

**Upgrading from 1.1.x or 1.3.x:** Update your `mix.exs` dependency to `{:lattice_stripe, "~> 1.7"}`. Review the milestone sections below for additive surfaces (Tax, thin events, Charge list/search/update/capture) and the **1.5.0** webhook tolerance migration if you use `tolerance: 0` in tests.

### Added

- **Charge surface expansion** — `LatticeStripe.Charge` gains `list/3`, `list!/3`, `stream!/3`, `search/3`, `search!/3`, `search_stream!/3`, `update/4`, `update!/4`, `capture/4`, and `capture!/4` for support, audit, and Connect reconciliation. PaymentIntent remains the payment-initiation path (`create`/`cancel` intentionally omitted). See [Charge moduledoc](https://hexdocs.pm/lattice_stripe/LatticeStripe.Charge.html).
- **Operator playbooks** — `guides/production-checklist.md` (pre-launch boundaries) and `guides/event-debugging.md` (webhook diagnostic ladder from delivery boundary inward).
- **Install contract** — README, Getting Started, and other public surfaces document `{:lattice_stripe, "~> 1.7"}` aligned with the published package version.

## [1.6.0] — Tax

_Milestone included in 1.7.0. Not published separately to Hex._

### Added

- **Tax.Calculation** — `create/3`, `retrieve/3`, `list_line_items/3` for standalone tax calculation (90-day expiry documented in moduledoc).
- **Tax.Transaction** — `create_from_calculation/3`, `create_reversal/3`, `retrieve/3`, `list_line_items/3` for recording and reversing tax liability.
- **Tax.Settings** — singleton retrieve/update for account-level tax configuration.
- **Tax.Registration** — jurisdiction registration CRUDL with `stream!/3`.
- **TaxId** — dual-path customer and account tax ID management.
- **`guides/tax.md`** — canonical Tax adoption guide with scope boundary vs `Invoice.AutomaticTax`.

## [1.5.0] — Thin-Event Webhooks

_Milestone included in 1.7.0. Not published separately to Hex._

### Fixed

- **`Webhook.check_tolerance/2` `tolerance: 0` semantics reconciled.**
  Before this release, `tolerance: 0` returned `{:error, :timestamp_expired}`
  on every call — directly contradicting the `verify_signature/4` docstring
  which has always documented `0` as "disable staleness check". The code clause
  has been corrected to match the docstring (and every canonical Stripe SDK:
  stripe-node's `if (tolerance > 0 && ...)` gate, stripe-go's `IgnoreTolerance`
  flag, stripe-ruby's `if tolerance && ...` guard).
- **`Webhook.Plug` NimbleOptions `:tolerance` schema relaxed.**
  Changed from `:pos_integer` to `:non_neg_integer` so the documented
  "Set 0 to disable" lever is reachable through the public Plug surface.
  Negative tolerances are still rejected at `init/1` time. **Testing only**
  — never set `tolerance: 0` in production; it removes replay-attack protection.
  See `guides/webhooks-thin-events.md` for the canonical thin-event path.

### Added

- **Thin-event SDK surface** — `Webhook.parse_event_notification/4`, `fetch_event/3`, `fetch_related_object/3` with typed `EventNotification` struct and `Event` extensions for `related_object` and `context`.
- **`guides/webhooks-thin-events.md`** — canonical Phoenix thin-event guide: fetch-after-verify idempotency on `event.id`, verification-vs-payload-shape failure boundary, Stripe 100 req/s rate-limit ceiling, Connect routing via `event.context`.
- **Testing helpers** — thin-event payload builders in `LatticeStripe.Testing` for signed wire-format fixtures.

## [1.4.0] — Adoption Closure

_Milestone included in 1.7.0. Not published separately to Hex._

### Added

- **Flagship recipes** — `guides/checkout-signup-and-portal.md`, `guides/connect-platform-flow.md`, `guides/metering-runtime-and-reconciliation.md`, `guides/quote-to-billing-operator.md` with cross-linked discovery ladder.
- **Guide discovery** — JTBD routing layer, cheatsheet, and README docs ladder for evaluating and navigating shipped surfaces.

## [1.3.0](https://github.com/szTheory/lattice_stripe/compare/v1.2...v1.3) (2026-05-25)

### Changed

- **Expand deserialization** — When you pass `expand: ["customer"]` (or any expandable field), the response struct now contains a fully typed struct (e.g., `%Customer{}`) instead of a raw map. Fields that are not expanded remain as string IDs, unchanged. This applies to all resource modules.

  **Migration note:** If your code pattern-matches on expanded fields expecting a raw map, update to match on the typed struct:

  ```elixir
  # Before (v1.1):
  {:ok, %PaymentIntent{customer: %{"id" => id}}} = PaymentIntent.retrieve(client, id, expand: ["customer"])

  # After (v1.2):
  {:ok, %PaymentIntent{customer: %Customer{id: id}}} = PaymentIntent.retrieve(client, id, expand: ["customer"])
  ```

  If you were not passing `expand:`, your code is unaffected — unexpanded fields are still string IDs.

- **Status atomization** — All resource modules with a documented finite `status` field now return atoms (e.g., `:active`, `:succeeded`) instead of strings from `from_map/1`. Unknown or future status values pass through as raw strings for forward-compatibility.

  **Migration note:** If your code compares status as a string, update to atom comparison:

  ```elixir
  # Before (v1.1):
  if pi.status == "succeeded" do ...

  # After (v1.2):
  if pi.status == :succeeded do ...
  ```

  Affected modules: PaymentIntent, Subscription, SubscriptionSchedule, Charge, Refund, SetupIntent, Payout, BalanceTransaction, BankAccount, Checkout.Session, Billing.Meter, Account.Capability.

- **Deprecated** `Billing.Meter.status_atom/1` and `Account.Capability.status_atom/1` — status is now automatically atomized in `from_map/1`/`cast/1`. Access `.status` directly on the struct.
- **Docs/package truth** — README, ExDoc extras, and public guide discovery align
  with the shipped `1.3.x` surface instead of presenting the line as unreleased.

### Added

- **v1.3 surface** — adds File/FileLink upload/download support,
  Disputes, Credit Notes, Mandates, SetupAttempts, Quotes, public testing fixture
  builders, a compact recipes guide, and a canonical Phoenix webhook quickstart.

- **Docs: User Flows & JTBD guide** — Added a new conceptual guide aimed at experienced
  Elixir/Phoenix SaaS integrators. It explains LatticeStripe through real product jobs and
  end-to-end flow choices, including when to use Checkout vs direct APIs, how subscriptions,
  invoices, portal sessions, metering, and webhooks fit together, and where current roadmap
  gaps still exist.
- Internal object-type dispatch module for expandable Stripe resources (not part of public API).
- Union type specs (`Customer.t() | String.t() | nil`) on all expandable fields across all resource modules.

### Fixed

- **Getting Started guide version drift** — Updated the install snippet to `{:lattice_stripe, "~> 1.3"}`
  and aligned the first `PaymentIntent` example output with atomized status values.

## [1.1.0](https://github.com/szTheory/lattice_stripe/compare/v1.0.0...v1.1.0) (2026-04-14)

### Highlights

The first post-1.0 minor release. Adds the two downstream unblockers needed by [Accrue](https://github.com/szTheory/accrue): usage-based billing (Billing Metering) and customer self-service (Customer Portal). Full phase history is in [PR #9](https://github.com/szTheory/lattice_stripe/pull/9).

**What's new:**
- **Billing Metering.** `Billing.Meter` CRUDL plus `deactivate/3` and `reactivate/3`, usage event ingestion via `MeterEvent.create/3`, and late corrections via `MeterEventAdjustment.create/3`. A pre-flight guard (`GUARD-03`) raises `ArgumentError` on malformed `value_settings` before the network call, preventing Stripe's silent-zero trap for `sum`/`last` aggregation formulas.
- **Customer Portal.** `BillingPortal.Session.create/3` returns a short-lived portal URL for a given customer. Full deep-link flow support (`subscription_cancel`, `subscription_update`, `subscription_update_confirm`, `payment_method_update`) via a 5-module nested `FlowData` struct tree. A pre-flight guard raises `ArgumentError` with actionable messages for missing required flow sub-fields, so malformed requests fail before they hit Stripe. The `Inspect` protocol masks the portal URL and flow to keep short-lived secrets out of log output.
- **Docs.** New `guides/metering.md` (usage-reporting idiom, idempotency two-layer explainer, reconciliation, backdating window, aggregation semantics) and `guides/customer-portal.md` (all 4 flow types with required sub-fields, Accrue-style Phoenix controller example, Inspect masking security teaching). New ExDoc groups: "Billing Metering" and "Customer Portal". Reciprocal cross-links from existing `guides/subscriptions.md` and `guides/webhooks.md`.

**Verification.** 1488 tests passing. Integration tests run against `stripe-mock`. `mix compile --warnings-as-errors`, `mix credo --strict`, and `mix docs --warnings-as-errors` all clean. Phase 20 and Phase 21 verification reports: passed.

**Upgrading from 1.0.x.** No breaking changes. Additive only — `Billing.Meter`, `Billing.MeterEvent`, `Billing.MeterEventAdjustment`, and `BillingPortal.Session` are new public modules. Existing code keeps working unchanged.

### Features

* **Billing.Meter:** `create/3`, `retrieve/3`, `update/4`, `list/2`, `deactivate/3`, `reactivate/3`
* **Billing.Meter.ValueSettings, DefaultAggregation, CustomerMapping, StatusTransitions:** nested typed structs with `:extra` forward-compat
* **Billing.MeterEvent:** `create/3` with two-layer idempotency (`identifier` vs `idempotency_key:`)
* **Billing.MeterEventAdjustment:** `create/3` with nested `Cancel` struct for late corrections
* **Billing.Guards.check_meter_value_settings!/1:** pre-flight shape guard for `value_settings` (GUARD-03, prevents silent-zero trap)
* **BillingPortal.Session:** `create/3` returns `{:ok, %Session{url: ..., flow: ...}}`
* **BillingPortal.Session.FlowData:** 5-module nested struct tree — `FlowData`, `AfterCompletion`, `SubscriptionCancel`, `SubscriptionUpdate`, `SubscriptionUpdateConfirm`
* **BillingPortal Guards:** pre-flight `check_flow_data!/1` raises `ArgumentError` for missing flow sub-fields, enumerating valid flow types on unknown input
* **Inspect masking for BillingPortal.Session:** hides `:url` and `:flow` fields via explicit allowlist to keep short-lived portal URLs out of logs
* **guides/metering.md:** usage-reporting idiom, idempotency layers, reconciliation, aggregation semantics
* **guides/customer-portal.md:** all 4 flow types, Accrue-style Phoenix controller example, Inspect masking security teaching
* **mix.exs:** `groups_for_modules` entries for "Billing Metering" and "Customer Portal"; both guides added to `extras`

## [1.0.0](https://github.com/szTheory/lattice_stripe/compare/v0.2.0...v1.0.0) (2026-04-13)

### Highlights

LatticeStripe 1.0 marks our commitment to API stability for the Elixir + Stripe integration story. The 0.2 → 1.0 journey spans four major milestones: a solid foundation of transport, retries, pagination, and observability (Phases 1-11); full Billing coverage for Invoices, Subscriptions, SubscriptionItems, and Subscription Schedules (Phases 14-16); end-to-end Connect support including accounts, onboarding links, external accounts, transfers, payouts, balance, and balance transactions (Phases 17-18); and a formalized public API surface with `@moduledoc false` internals and an explicit semver contract (Phase 19). Starting with 1.0.0, LatticeStripe follows standard semver: patch releases for bug fixes, minor releases for additive features, major releases for breaking public API changes — see [API Stability](guides/api_stability.md) for the full contract.

**What's in the box:**
- **Payments.** Customers, PaymentIntents, SetupIntents, PaymentMethods, Refunds, Checkout Sessions.
- **Billing.** Invoices (create, finalize, pay, void, send, search), Subscriptions with lifecycle verbs and pause helpers, Subscription Schedules with proration guards, Invoice Items.
- **Connect.** Accounts (Standard/Express/Custom), Account Links, Login Links, External Accounts (BankAccount/Card), Transfers + TransferReversals, Payouts (with TraceId), Balance + BalanceTransactions, Charge retrieve for fee reconciliation.
- **Webhooks.** Timing-safe signature verification, `Event` struct, Phoenix `Webhook.Plug`, `Webhook.Handler` behaviour.
- **Operational glue.** Pluggable `Transport`/`Json`/`RetryStrategy` behaviours, Telemetry events for every request, `LatticeStripe.Testing` helpers with TestClock support.

**Upgrading from 0.2.x.** No breaking API changes from 0.2. The public surface has been frozen; previously-visible internal modules (`FormEncoder`, `Request`, `Resource`, `Transport.Finch`, `Json.Jason`, `RetryStrategy.Default`, `Webhook.CacheBodyReader`, `Billing.Guards`) are now documented as private via `@moduledoc false` and are excluded from the semver contract.

**Supported versions.** Elixir 1.15+ on OTP 26+, tested up to Elixir 1.19 on OTP 28.

### Features

* **17-01:** add canonical Account/AccountLink/LoginLink fixtures ([a1a101c](https://github.com/szTheory/lattice_stripe/commit/a1a101cc15d87a1d47b15abad4d3a5109edb934a))
* **17-01:** add stripe-mock reject probe script and record result in VALIDATION.md ([e3539e9](https://github.com/szTheory/lattice_stripe/commit/e3539e9ae0a524d27997028fafb5a5d108f7314a))
* **17-02:** Account.Capability (D-02) with safe status_atom/1 ([3a80de4](https://github.com/szTheory/lattice_stripe/commit/3a80de499f52a4f4e93b7ab58ca33fd91c642fa0))
* **17-02:** PII-safe nested structs — TosAcceptance, Company, Individual ([fddb864](https://github.com/szTheory/lattice_stripe/commit/fddb8647e6030f8634ade3c2f92fa3d1b5364e3d))
* **17-02:** plain nested structs — BusinessProfile, Requirements, Settings ([4bd03c9](https://github.com/szTheory/lattice_stripe/commit/4bd03c9f6c0aeea3af1533150077f138dcaa408e))
* **17-03:** LatticeStripe.Account resource module — CRUD + reject + stream + from_map ([92747d0](https://github.com/szTheory/lattice_stripe/commit/92747d09235ce8b8cc839231b807fa1ff41b6336))
* **17-04:** LatticeStripe.AccountLink — create/3, create!/3, from_map/1 + tests ([7161f34](https://github.com/szTheory/lattice_stripe/commit/7161f34cddbce228ed8dfa7e8b91336b7ad166c6))
* **17-04:** LatticeStripe.LoginLink — create/4, create!/4, from_map/1 + tests ([0bd48d7](https://github.com/szTheory/lattice_stripe/commit/0bd48d707a125f63c9d163e43814a8285e0d176f))
* **17-05:** Account full-lifecycle integration test + fix cast_capabilities for stripe-mock ([e1364a6](https://github.com/szTheory/lattice_stripe/commit/e1364a6816d040006eb03a6885748225afaab188))
* **17-05:** AccountLink + LoginLink integration tests (9 tests each) ([ecb7494](https://github.com/szTheory/lattice_stripe/commit/ecb74948400c1535c077ce418b07bbee9e0079c5))
* **17-06:** add guides/connect.md — Connect onboarding narrative ([874dda9](https://github.com/szTheory/lattice_stripe/commit/874dda9ce161c9bb57581e8f58011420a8568836))
* **18-01:** add BankAccount + Card structs with F-001 and PII Inspect ([f775aff](https://github.com/szTheory/lattice_stripe/commit/f775aff07ef162842e544070f75b610f713b8f71))
* **18-01:** add ExternalAccount polymorphic dispatcher + Unknown fallback ([91148ac](https://github.com/szTheory/lattice_stripe/commit/91148ac963ada48c81da3e5d3ce2238c13b22f36))
* **18-02:** add LatticeStripe.Charge retrieve-only resource ([44a0adb](https://github.com/szTheory/lattice_stripe/commit/44a0adb6cf05b2f4a342403cb335dafab7993c42))
* **18-03:** add LatticeStripe.Transfer CRUDL with embedded reversals decoding ([90b1234](https://github.com/szTheory/lattice_stripe/commit/90b1234d730873dd0845f015cfe6818cf8c54fb6))
* **18-03:** add LatticeStripe.TransferReversal standalone module ([5cddcb9](https://github.com/szTheory/lattice_stripe/commit/5cddcb91d4b22ca4bd12278eaff6e7ef94c47b8b))
* **18-04:** add Payout CRUDL + cancel + reverse with TraceId integration ([79605ae](https://github.com/szTheory/lattice_stripe/commit/79605ae8c98fe2b3f9b6616c39a232459fc2bcd1))
* **18-04:** add Payout.TraceId nested typed struct ([52f6d11](https://github.com/szTheory/lattice_stripe/commit/52f6d11647733a80d741a33779734ee7e33082fc))
* **18-05:** add Balance singleton with Amount and SourceTypes nested structs ([5304b80](https://github.com/szTheory/lattice_stripe/commit/5304b80d0235b894b0148d2cd41c8c7e8d1c5d9c))
* **18-05:** add BalanceTransaction retrieve/list/stream + FeeDetail struct ([6873c5f](https://github.com/szTheory/lattice_stripe/commit/6873c5f553773e4e55013a9e835749be3a8f1bf8))
* **19-01:** rewrite mix.exs groups_for_modules to nine-group D-19 layout ([c66223b](https://github.com/szTheory/lattice_stripe/commit/c66223b2ed32a6c02eeddbdf704871cbb6e9288b))


### Bug Fixes

* **17-02:** align nested struct tests with 17-01 canonical fixture values ([025082a](https://github.com/szTheory/lattice_stripe/commit/025082a9fb04ca973394d1e818b8a1df098999ca))
* **18:** IN-01 correct BankAccount docstring account_number reference ([b720afa](https://github.com/szTheory/lattice_stripe/commit/b720afa066fb10e762b6f5e52798c3505f8b234a))
* **18:** IN-02 normalize nil/empty id guards to 'id in [nil, ""]' style ([542fc1b](https://github.com/szTheory/lattice_stripe/commit/542fc1bae0e3c88fae302e97e50b5e019ba95bac))
* **18:** IN-03 derive ExternalAccount.Unknown.cast drop list from [@known](https://github.com/known)_fields ([00d618e](https://github.com/szTheory/lattice_stripe/commit/00d618ed285675fca67836acddd1ee9e6576b351))
* **18:** IN-04 add is_map(params) guard to Payout.update/update! ([bdc4ab8](https://github.com/szTheory/lattice_stripe/commit/bdc4ab8c29f92e271ba0d1c0f83efa2fe8ebb582))
* **18:** IN-05 preserve unexpected Transfer reversals shape in extra ([ae1c85e](https://github.com/szTheory/lattice_stripe/commit/ae1c85e5ffef88a9a903758a738f7bb736e67d5d))
* **18:** WR-01 add map() to Transfer expandable typespecs ([772795e](https://github.com/szTheory/lattice_stripe/commit/772795e34c128552986a9063e75e6e8f3da598a7))
* **18:** WR-01 add map() to TransferReversal expandable typespecs ([fe9bbdd](https://github.com/szTheory/lattice_stripe/commit/fe9bbddab275cfbc7827a73d4ca541be512bfc1a))
* **18:** WR-02 add map() to Charge destination/source_transfer typespecs ([c26187d](https://github.com/szTheory/lattice_stripe/commit/c26187d10bddd32bf5130a2653193462ab0aeaac))
* **18:** WR-03 add nil/empty id guards to BalanceTransaction.retrieve/3 and retrieve!/3 ([e60f220](https://github.com/szTheory/lattice_stripe/commit/e60f2201bf5596ac8357c0dfcee745f3e356cda7))
* **18:** WR-03 add nil/empty id guards to Payout.update/4 and update!/4 ([4614b1c](https://github.com/szTheory/lattice_stripe/commit/4614b1c501443d04208f5fecf6a07b002da998ab))
* **18:** WR-03 restore balance_transaction id error message for test contract ([10a8827](https://github.com/szTheory/lattice_stripe/commit/10a882718bb277f25f39a5e62a5f90894eac70c5))

## [0.2.0](https://github.com/szTheory/lattice_stripe/compare/v0.1.0...v0.2.0) (2026-04-04)


### Features

* **01-01:** configure test infrastructure with Mox mocks, formatter, and Credo ([d75666e](https://github.com/szTheory/lattice_stripe/commit/d75666e3eaefbc8d1bffe5d641e73408cd3ef94d))
* **01-01:** scaffold Elixir project with Phase 1 dependencies ([2e4ae58](https://github.com/szTheory/lattice_stripe/commit/2e4ae5814b004e4e299d8d0244258fbc8cfb1f3e))
* **01-02:** implement JSON codec behaviour and Jason adapter with tests ([bb63aac](https://github.com/szTheory/lattice_stripe/commit/bb63aacd7b431fc5d3579515118547c74054e089))
* **01-02:** implement recursive Stripe-compatible form encoder with tests ([2c232e4](https://github.com/szTheory/lattice_stripe/commit/2c232e41dbb88cf31015adfb4e318b397d0e5391))
* **01-03:** implement Error struct with Stripe error response parsing and tests ([8438a4c](https://github.com/szTheory/lattice_stripe/commit/8438a4c948aaf27c73eea8f84731b36601a8f2cc))
* **01-03:** implement Transport behaviour and Request struct with tests ([192ddc9](https://github.com/szTheory/lattice_stripe/commit/192ddc9903e1774170c08983ff4edfdf60095199))
* **01-04:** implement Finch transport adapter with tests ([b0951e3](https://github.com/szTheory/lattice_stripe/commit/b0951e3efc660fa9c4655c97696811c29c942711))
* **01-04:** implement NimbleOptions config schema and validation with tests ([9441d19](https://github.com/szTheory/lattice_stripe/commit/9441d190846a437f3ff5f3b5289356ce56f2fc1b))
* **01-05:** implement Client struct with new!/1, new/1, and request/2 ([8c384d8](https://github.com/szTheory/lattice_stripe/commit/8c384d812ac996d4d03eec6ac0bbf8e0366e7990))
* **02-01:** add non-bang decode/1 and encode/1 to Json behaviour and Jason adapter ([1666da4](https://github.com/szTheory/lattice_stripe/commit/1666da4aaf59d4197957abf605178a11595350d0))
* **02-01:** enrich Error struct with new fields, idempotency_error, String.Chars ([33da331](https://github.com/szTheory/lattice_stripe/commit/33da331438938466e3e6f6ab7cf04b13db3386cf))
* **02-02:** implement RetryStrategy behaviour and Default implementation ([f2394e7](https://github.com/szTheory/lattice_stripe/commit/f2394e76ca9d518089290c1ced3ef670800c97ab))
* **02-02:** update Config and Client with retry_strategy field and max_retries default 2 ([f3df360](https://github.com/szTheory/lattice_stripe/commit/f3df36074f27fb11cb0b3497117420f5b2e7880c))
* **02-03:** wire retry loop, auto-idempotency, bang variant, non-JSON handling into Client ([9501f91](https://github.com/szTheory/lattice_stripe/commit/9501f91b9951f46ed150091026080669463f9152))
* **03-01:** add List struct, api_version/0, update Config/Client defaults and User-Agent ([f7b30af](https://github.com/szTheory/lattice_stripe/commit/f7b30af27416de107436457da0099d61a5078db6))
* **03-01:** add Response struct with Access behaviour, get_header/2, custom Inspect ([8a97dc8](https://github.com/szTheory/lattice_stripe/commit/8a97dc84b10b37cad84d50f3fb0630b8d3ccb759))
* **03-02:** wrap responses in %Response{} with list auto-detection ([9051f8c](https://github.com/szTheory/lattice_stripe/commit/9051f8c529dfb6a3e01c9e6b52c24e37321acf7b))
* **03-03:** implement stream!/2 and stream/2 auto-pagination on List ([dc2b01a](https://github.com/szTheory/lattice_stripe/commit/dc2b01a15cabdb1ed8ad50c02fbe8b1c156b4ef6))
* **04-01:** implement LatticeStripe.Customer resource module ([420f4a2](https://github.com/szTheory/lattice_stripe/commit/420f4a2868ccf7acb78c43d30ed870cdd21a5d5d))
* **04-02:** implement LatticeStripe.PaymentIntent resource module ([30b55c8](https://github.com/szTheory/lattice_stripe/commit/30b55c80a1f04577e23609f458a32639670af4ca))
* **05-01:** build SetupIntent resource module with full CRUD, lifecycle actions, list/stream, and tests ([7908ede](https://github.com/szTheory/lattice_stripe/commit/7908ededee79e51e98e32bfb3a1f994751d071fc))
* **05-01:** extract Resource helpers, refactor Customer/PaymentIntent, add PI search, shared test helpers ([0a85316](https://github.com/szTheory/lattice_stripe/commit/0a853162f93c4f447443f3611e1fe492e2190e00))
* **05-02:** implement PaymentMethod resource with CRUD, attach/detach, validated list, stream, and tests ([ec48dca](https://github.com/szTheory/lattice_stripe/commit/ec48dca7da388595020c48a80748a4c46f5182dd))
* **06-01:** extract Phase 4/5 test fixtures into dedicated fixture modules ([bd69567](https://github.com/szTheory/lattice_stripe/commit/bd695671dc2c6ec1cde12c955f9752295b6aba06))
* **06-01:** implement Refund resource with CRUD, cancel, list, stream, and tests ([8e4ecad](https://github.com/szTheory/lattice_stripe/commit/8e4ecad6bbd037f957a14ae1c5cc6f7661714c08))
* **06-02:** implement Checkout.Session and LineItem with all endpoints and tests ([99dbadd](https://github.com/szTheory/lattice_stripe/commit/99dbaddec03c69f3361fee3e1bd508cfc422e191))
* **07-01:** add Event struct, Handler behaviour, SignatureVerificationError, deps ([1c04f4b](https://github.com/szTheory/lattice_stripe/commit/1c04f4bbf6823aa2d448b740a131d967b11fb1a5))
* **07-01:** implement LatticeStripe.Webhook with HMAC-SHA256 verification ([b524010](https://github.com/szTheory/lattice_stripe/commit/b52401010825a803778594f77673cafd92dc6b41))
* **07-02:** add CacheBodyReader and Webhook.Plug with NimbleOptions, path matching, handler dispatch, MFA secrets ([08eed78](https://github.com/szTheory/lattice_stripe/commit/08eed78e65b7c0ef06e868638d7817d32bbb095b))
* **08-01:** create LatticeStripe.Telemetry module with event catalog and span helpers ([c8e514e](https://github.com/szTheory/lattice_stripe/commit/c8e514e51bf9876ad27416e01b673a819f73c49f))
* **08-02:** implement webhook_verify_span, attach_default_logger, integrate webhook telemetry ([63de0a4](https://github.com/szTheory/lattice_stripe/commit/63de0a489da038e56b8e3aa7802b1eb683a6912f))
* **09-01:** add 6 resource integration test files ([87cb6ab](https://github.com/szTheory/lattice_stripe/commit/87cb6abc24b9683eb1325b898da03853a10f1aae))
* **09-01:** add integration test infrastructure ([c37a9ec](https://github.com/szTheory/lattice_stripe/commit/c37a9ecc71fef9d9a389fd8b1c00a79ce288ee77))
* **09-02:** add mix ci alias, Credo strict mode, and fix all violations ([152eacc](https://github.com/szTheory/lattice_stripe/commit/152eaccb9c26be837f5d7348d391e85c3bf5c331))
* **09-02:** implement LatticeStripe.Testing public module ([60506ed](https://github.com/szTheory/lattice_stripe/commit/60506ed1fb86cc692e22e5c84ba359b3d01eb2dd))
* **10-01:** complete cheatsheet with two-column layout ([52368ea](https://github.com/szTheory/lattice_stripe/commit/52368eab0046a5b517ab0f5ff1808b95ab5ad71f))
* **10-01:** ExDoc config, README quickstart, CHANGELOG, guide stubs ([677b034](https://github.com/szTheory/lattice_stripe/commit/677b034121ae0a4d22695519f1db6f5a572036b0))
* **10-02:** add [@typedoc](https://github.com/typedoc) and Stripe API reference links to resource modules ([70ab5f4](https://github.com/szTheory/lattice_stripe/commit/70ab5f4f458ca41619cb3c1eeb2a12bff5f885df))
* **10-02:** add @moduledoc/@doc/[@typedoc](https://github.com/typedoc) to core and internal modules ([32b1917](https://github.com/szTheory/lattice_stripe/commit/32b1917f7ce7f3ec1b34eaff8f6d5cf834cec025))
* **10-03:** write checkout and webhooks guides ([3b04b13](https://github.com/szTheory/lattice_stripe/commit/3b04b131f580ef34e15a108a07e8e65601fc8737))
* **10-03:** write getting-started, client-configuration, and payments guides ([781f10e](https://github.com/szTheory/lattice_stripe/commit/781f10e6ebd64074373d8aa96b6251e70eb35da2))
* **11-02:** add Dependabot config and auto-merge workflow ([12078f6](https://github.com/szTheory/lattice_stripe/commit/12078f68eb8a4dfd106cf2fbb9ee0de7e4489e34))
* **11-02:** add Release Please workflow and manifest config ([a478928](https://github.com/szTheory/lattice_stripe/commit/a478928e4ac454efeae0f4f125fbba46744b2916))
* **11-03:** add community files — CONTRIBUTING, SECURITY, issue templates, PR template ([36d6a7a](https://github.com/szTheory/lattice_stripe/commit/36d6a7ab8fffad54db80e95785541318c84114f9))


### Bug Fixes

* **01:** resolve verification gaps — update REQUIREMENTS.md traceability and fix flaky test ([4edc9ad](https://github.com/szTheory/lattice_stripe/commit/4edc9adc7ce78fb755d109883114a8d9f185a2c6))
* **01:** revise plans based on checker feedback ([3226334](https://github.com/szTheory/lattice_stripe/commit/3226334939d90eb1084ebfb5ec17094cab2422d0))
* **03:** remove deferred requirements EXPD-02, EXPD-03, EXPD-05 from Plan 02 ([ca8372e](https://github.com/szTheory/lattice_stripe/commit/ca8372ec46d58cfd8d14e4d7e3bf2c9810583a23))
* **04:** Customer Inspect uses Inspect.Algebra to prevent PII field name leakage ([63ae62e](https://github.com/szTheory/lattice_stripe/commit/63ae62e77eb06dfdb63b356824bda2d908360d0d))
* **04:** remove unused aliases in test files ([9780bdf](https://github.com/szTheory/lattice_stripe/commit/9780bdf01c4216dafe0f39f069265ea5f26839e3))
* **09:** revise plans based on checker feedback ([9a59458](https://github.com/szTheory/lattice_stripe/commit/9a59458a11bf60799feb788d2a00fa8b7705c1d2))
* remove deprecated 'command' input from release-please-action v4 ([3ff8a12](https://github.com/szTheory/lattice_stripe/commit/3ff8a12fa3090eb69344a2c4d4ba418036cb5d7d))
* skip invalid-id integration tests — stripe-mock returns stubs for any ID ([e986f1b](https://github.com/szTheory/lattice_stripe/commit/e986f1bb67c9bf51602d108ab7d6af23a5323844))
* update GitHub org from lattice-stripe to szTheory ([ad46956](https://github.com/szTheory/lattice_stripe/commit/ad469565578f4791ba29c6bb46544750bee7018e))