Skip to content

feat(v2): Add lago v2 apply to manage the catalog from YAML files - #42

Open
jdenquin wants to merge 1 commit into
mainfrom
feat/v2-apply
Open

jdenquin wants to merge 1 commit into
mainfrom
feat/v2-apply

Conversation

@jdenquin

Copy link
Copy Markdown
Contributor

What

lago v2 apply DIR makes an organization's product catalog match a folder of YAML files, so the catalog can live in git and be reviewed like code. It covers billable metrics, product categories, products, rate cards with their rates, and plans with their applied rate cards, all matched by code.

$ lago v2 apply billing/ --dry-run      # print the plan, send nothing
$ lago v2 apply billing/                # create and update
$ lago v2 apply billing/ --prune --confirm prune   # also delete what the files dropped
  • Plan first. apply prints one line per object (create, update with the changed fields, unchanged, delete), then writes in dependency order and sends only the fields that changed.
  • Bad changes are refused before any write. That covers unknown fields, references to codes that don't exist, duplicate codes, and changes the API can't make in place, like a product's product_type.
  • Values compare semantically. "0.70" matches 0.7, and 2026-11-11T00:00:00.000000Z matches 2026-11-11T00:00:00Z. Without this, each run would try to update every active rate, and the API refuses that.
  • Deleting needs --prune and a confirmation. The objects the folder created or adopted are recorded in DIR/.lago-state/<organization id>.json, and only those can be deleted, so another team's objects in a shared org are never touched. A declared plan's applied rate cards and a declared rate card's pending rates match the files exactly. Active and terminated rates are history and are kept. Plans have no v2 delete route, so a dropped plan is released from the state instead.
  • A failed write stops the run. The state records what went through, so a rerun picks up where it stopped.

The reasoning is in DECISIONS.md ("lago v2 apply").

API and spec gaps found on the way

  • The v2 OpenAPI document leaves description out of the update bodies for products, product categories, rate cards and plans, but lago-api accepts it. apply takes its field lists from the controllers' strong params for now; the spec should be fixed upstream.
  • A rate's effective_from can't be before today (must_not_be_before_today), even inside a new rate card, so the dates in the Notion example payloads no longer work as-is.

QA

Run against a local lago-api (org with the product_catalog flag), using the Lago for Lago billing configuration from the self-serve spec:

  • First apply: 14 creates, the same calls as the spec. Running it again: everything unchanged.
  • Partial failure (rate dated in the past): stopped after 7 writes, state recorded, the rerun created the remaining 7.
  • Updates: a category's display name, a product's description, the units of an applied rate card, the amount of an active rate, and a new pending rate. 5 writes, and the next run was unchanged.
  • Refusals before any write: immutable product_type, unknown field, unknown category code.
  • Prune: added a temporary metric, product and rate card attached to the plan, then dropped them along with a pending rate. Without --prune they were listed as skipped. Without --confirm it was refused. With both, 5 deletes ran in reverse dependency order. The org's other objects (growth, standard_usd, platform_fee, catalog_api_calls) were untouched, and the active rate was kept.
  • Dropping the plan released it; declaring it again adopted it back.

make test, lint, moneycheck, the coverage floors (internal/cli 90.1%) and make generate-check pass. The new tests use an in-memory fake of the v2 catalog API with cursor pagination.

🤖 Generated with Claude Code

`lago v2 apply DIR` makes the product catalog match a folder of YAML
files: billable metrics, product categories, products, rate cards with
their rates, and plans with their applied rate cards, matched by code.
It prints a plan (`--dry-run` stops there), then creates and updates in
dependency order with only the changed fields. A change the API cannot
make in place is refused before anything is sent.

Decimals and timestamps compare by value, so the API's "0.70" and
microsecond timestamps do not show up as changes on every run.

Nothing is deleted without `--prune`. The objects the folder created or
adopted are recorded in DIR/.lago-state/<organization id>.json, and
`--prune` only deletes those, after confirmation. A shared organization's
other objects are never touched, and neither are active or terminated
rates. Plans have no v2 delete route, so a dropped plan is released.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants