fix(events): align instant fee estimate schemas with API

[groyoh]

Context

OpenAPI guardian check of events (full run), compared with lago-api at 25b8b7b and the SDK clients. A human must review and merge this PR; the agent never merges.

Description

Breaking for generated clients

• EventBatchEstimateInstantFeesInput.events[]: { "event": { ... } } → { "code", "external_subscription_id", "properties", "transaction_id" }. The API reads each item as a flat event and groups the items by external_subscription_id, so a body in the old shape fails with a subscription not found error. The event fields moved to the new EventEstimateInstantFeesInputObject schema. EventEstimateInstantFeesInput now references it, so POST /events/estimate_instant_fees is unchanged.

  Code references (lago-api at 25b8b7b)

  • Controller: EventsController#batch_estimate_instant_fees groups batch_params[:events] by external_subscription_id.
  • Controller: EventsController#batch_params permits flat event keys under events, with no event wrapper.
  • Service: Fees::EstimateInstant::BatchPayInAdvanceService#initialize builds each event from code, external_subscription_id, properties and transaction_id, and fails with not_found when no subscription matches.
  • Request spec: POST /api/v1/events/batch_estimate_instant_fees sends flat event hashes.

• FeeEstimateObject.item.description: string → string or null. It is the billable metric description, which is nullable. The field text also said it was the metric name. It now says it is the metric description. Affects POST /events/estimate_instant_fees and POST /events/batch_estimate_instant_fees.

  Code references (lago-api at 25b8b7b)

  • Service: Fees::EstimateInstant::BaseService#estimate_charge_fees sets item.description to billable_metric.description.
  • Schema: db/structure.sql billable_metrics.description is character varying without NOT NULL.

Other changes

• Typos in FeeEstimateObject: "It will always returns 0", "The value will always pending", "Values is BillableMetric".

SDK drift (spec is right, needs an sdk-clients-update run)

Client	Divergence
Ruby, Python, Go	No method for POST /events/estimate_instant_fees or POST /events/batch_estimate_instant_fees.
Python, Go	No method for GET /events (list with filters).
Go	EventEstimateFeesInput misses precise_total_amount_cents, which Fees::EstimatePayInAdvanceService reads.

Suspected lago-api bugs (spec unchanged)

• Instant fee estimates: amount_cents, precise_amount, precise_total_amount and precise_unit_amount are built as BigDecimal in Fees::EstimateInstant::BaseService#estimate_charge_fees, so they are rendered as strings ("40.0"), while the contract says integer and number. The request specs assert amount_cents == "40.0" (events_controller_spec.rb#L773). POST /events/estimate_fees returns an integer for the same field.

Needs human confirmation (not changed)

• GET /events_enriched (beta, ClickHouse organizations only) is not in the spec. Should it be documented?
• external_contract_id is accepted on POST /events and POST /events/batch as an alias of external_subscription_id, but is not documented. Is it a public field of the v1 API?
• external_subscription_id is required and non-null on events in the spec, but the Event model only validates transaction_id and code. Should the spec keep the stricter contract?

Agent notes

Run: full, queue reason for this resource: full mode, group 0. Compatibility checker: BLOCK (advisory); every non-info finding is listed under Breaking (the three batch request findings are the shape fix, the two nullable findings are item.description).

The three questions under "Needs human confirmation" were first asked in #586 and have no answer yet.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.