feat(sdk): added python support for monthly billing report

[bmaydan]

What

Adds Organization.get_monthly_summary() for fetching an organization's monthly billing summary (credits purchased, used, and remaining) from the billing service.

Details

• OrgApi.get_monthly_summary() wraps billing_service_get_monthly_summary, exposing a single start/end interface that implicitly maps onto the API's two mutually exclusive filter modes:
  • both start and end: translated to a range filter.
  • only start: translated to a pivot filter with pivot=start, pivot_direction="AFTER".
  • only end: translated to a pivot filter with pivot=end, pivot_direction="BEFORE".
• Validates that at least one of start/end is provided, that start <= end when both are given, and that the requested span doesn't exceed the API's 2-year limit (also enforced for the implicit AFTER pivot relative to now).
• Organization.get_monthly_summary() exposes the same start/end interface at the SDK's public surface, scoped to self.id.

Example output

from lightning_sdk import Organization

org = Organization("my-org")
summary = org.get_monthly_summary(pivot=..., pivot_direction="BEFORE")
print(summary) ->
[
    {
      "periodStart": "2025-01-01T00:00:00Z",
      "periodEnd": "2025-02-01T00:00:00Z",
      "totalCreditsConsumed": (...),
      "totalCreditsRemaining": (...),
      "totalCreditsPurchased": (...)
    },
    {
      "periodStart": "2025-02-01T00:00:00Z",
      "periodEnd": "2025-03-01T00:00:00Z",
      "totalCreditsConsumed": (...),
      "totalCreditsRemaining": (...),
      "totalCreditsPurchased": (...)
    },
    ...
],

Testing

• Added unit tests in python/tests/api/test_org_api.py covering valid range/pivot usage and invalid-input cases (missing/both filters, inverted range, future AFTER pivot, >2 year spans).

[justusschock]

@bmaydan needs a pr description (ideally with an example output) :)

[bmaydan]

@bmaydan needs a pr description (ideally with an example output) :)

added!

[robTheBuildr]

@ethanwharris @justusschock looks good to me, not approving until you can validate as you previously blocked