feat: send the entitlement window, warning threshold and grant allowance

[Alex (Alexkuva)]

What does this PR change?

• EntitlementInput gains ResetPeriod, ResetAnchor, WarningThresholdPercent and the sale-unit trio (SaleUnitSingular, SaleUnitPlural, SaleUnitFactor), with EntitlementResetPeriod* and EntitlementResetAnchor* constants.
• Licenses.AssociateEntitlement and Licenses.UpdateEntitlement take an optional ...LicenseEntitlementOption. WithOveragePercent(n) sends the grant's limitCapExceededOveragePercent.
• The doc comments on EntitlementInput, Entitlements.Update and Licenses.UpdateEntitlement, and the README, say what each PUT does with an omitted field.

Why?

The Core request bodies declare these fields and internal/gen already reads them back, but no input could send them. Both PUTs replace rather than patch, so the gap was a set of bugs and not only missing features:

Call	Before this PR
Entitlements.Update on a periodic entitlement	Always refused with a 400, UpdateEntitlement.ImmutableResetPeriod: the API reads an omitted period as an attempt to remove it
Entitlements.Update on any entitlement	Warning threshold reset to 0 (off), sale unit cleared
Licenses.UpdateEntitlement on a soft limit	Allowance reset to the server default, 0: a hard limit

It is also what keeps a dataset seeded over the API from matching the OSS demo profile: the monthly window on monthly-orders, and the per-License allowances of 0, 10 and 20 %. The other SDKs already have all of this. sdk-python 1.0.0 exposes reset_period, reset_anchor, warning_threshold_percent, the sale units and overage_percent; @kaitencloud/server gets them through its generated EntitlementWritable and LicenseEntitlementWritable.

Server behavior this is written against, from kaiten main (c04b6b86):

• entitlements/updateentitlement/handler.go: the immutability checks, and an absent threshold resets to 0.
• entitlement.sql, UpdateEntitlement: COALESCE on the window only; every other optional column is overwritten.
• licenses/associateentitlementwithlicense/repository.go, resolveOveragePercent: the default is derived from the value, and -1 is accepted exactly when the value is unlimited. The update path is the same, with 400 …InvalidLimitCapExceededOveragePercent.
• pkg/apierrors: KindValidation answers 400.

Compatibility

task release:check (gorelease) reports:

• Incompatible: the two method signatures, because of the added variadic. Every existing call site compiles unchanged; only a method value or an interface declaring the old signature would break.
• Compatible: the new fields, types and constants, LicenseEntitlementOption and WithOveragePercent.
• Suggested version: v0.1.0.

Without the option, the grant bodies are byte for byte what they were (pinned by TestGrantWritesRenderTheOveragePercentOnlyWhenSet). Consumers checked: kaitencloud/cli builds against this branch, and every other call site we know of uses the four-argument form.

Testing

• task test (race, shuffle), task lint (0 issues), task fmt (no change), task deadcode.
• TestRequestBodiesMatchTheirSpecBodies: six new cases, covering a periodic entitlement's create and update, and a grant's associate and update with and without an allowance.
• New TestEntitlementAndGrantWritesReachEveryWritableKey.
  • It reads the body keys off gen.CreateEntitlementJSONRequestBody and the three other request types, minus the spec's readOnly fields, so a regenerated client with a new writable key fails until an input sends it.
  • Mutation-checked: dropping warningThresholdPercent from the update payload fails it.
• TestEntitlementWritesRenderTheWindowAndThresholdOnlyWhenSet, plus TestEntitlementUpdateCarriesThePeriodBack for the Get-then-Update round trip.
• TestGrantWritesRenderTheOveragePercentOnlyWhenSet: 0 and -1 are rendered, a nil option is skipped, the last option wins.
• Not run against a live kaiten.

After merge

Tag v0.1.0 (there is no release workflow, so the tag is the release). Then bump the consumers, the CLI among them. It merges cleanly with #1 (feat/billing).

Checklist

• I have read CONTRIBUTING.md.
• Every commit in this PR includes a valid DCO Signed-off-by line.
• I have the right to submit all material in this PR.
• I have not included secrets or confidential data.
• I have updated tests where appropriate.
• I have updated documentation where appropriate.
• I have preserved required third-party licenses and attributions.

🤖 Generated with Claude Code · ✅ Tested and approved by Alex (@Alexkuva), maintainer

[fuzcap]

this could be moved up to a common go package maybe