feat(usage): deprecate legacy periodic-usage endpoints [MOI-7251]

[adnilaM (malinda1986)]

Ticket: https://contentful.atlassian.net/browse/MOI-7251

Summary by Bito

This PR adds deprecation warnings to the legacy periodic-usage endpoints (organization_periodic_usages and space_periodic_usages) across the Contentful Management Ruby SDK. The changes affect 5 files by adding YARD Daniel Edeling (@deprecated) annotations and runtime warning messages that inform developers to migrate to the new Usage API before the 2027-02-28 removal date.

Detailed Changes

• Adds runtime deprecation warnings in client.rb to organization_periodic_usages and space_periodic_usages methods, alerting users the legacy endpoints will be removed on 2027-02-28
• Marks ClientOrganizationPeriodicUsageMethodsFactory and its all method as deprecated with YARD documentation
• Marks ClientSpacePeriodicUsageMethodsFactory and its all method as deprecated with YARD documentation
• Adds deprecation notices to OrganizationPeriodicUsage and SpacePeriodicUsage resource classes and their static all methods, directing users to migrate to the new Usage API

[bito-code-review]

Code Review Agent Run #6e0df2

Actionable Suggestions - 0

Additional Suggestions - 1

• lib/contentful/management/client_organization_periodic_usage_methods_factory.rb - 1

  • Runtime deprecation warning missing · Line 19-20
    The `all` method has a `@deprecated` YARD tag but no runtime `warn` call. Both upstream callers (`Client#organization_periodic_usages` and `OrganizationPeriodicUsage.all`) emit runtime warnings, so users of the public API will see deprecation notices. However, if the factory is called directly, callers receive no runtime warning. Add `warn '[DEPRECATION] ...'` at the start of the method body.

Filtered by Review Rules

Bito filtered these suggestions based on rules created automatically for your feedback. Manage rules.

• lib/contentful/management/organization_periodic_usage.rb - 1

  • Inconsistent method-level doc indent · Line 35-36
• lib/contentful/management/client.rb - 2

  • Duplicate deprecation warning · Line 148-153
  • Duplicate deprecation warning · Line 162-167

Review Details

• Files reviewed - 5 · Commit Range: c4dbe54..c4dbe54

  • lib/contentful/management/client.rb
  • lib/contentful/management/client_organization_periodic_usage_methods_factory.rb
  • lib/contentful/management/client_space_periodic_usage_methods_factory.rb
  • lib/contentful/management/organization_periodic_usage.rb
  • lib/contentful/management/space_periodic_usage.rb
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Ruby (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers a full AI review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[bito-code-review]

Changelist by Bito

This pull request implements the following key changes.

Key Change	Files Impacted	Summary
Feature Improvement - Legacy Usage API Deprecation	client.rb, client_organization_periodic_usage_methods_factory.rb, client_space_periodic_usage_methods_factory.rb, organization_periodic_usage.rb, space_periodic_usage.rb	Added Daniel Edeling (@deprecated) documentation and runtime warnings to all legacy periodic-usage API methods, indicating removal on 2027-02-28 with migration guidance to the new Usage API.

[bito-code-review]

Functional Validation by Bito

Source	Requirement / Code Area	Status	Notes
MOI-7251, Legacy-Endpoint-Deprecation, RFC-0011	Add Daniel Edeling (@deprecated) YARD tags with sunset date 2027-02-28 to legacy periodic-usage methods and classes in the Ruby SDK	✅ Met	All required methods and classes have Daniel Edeling (@deprecated) YARD tags with sunset date 2027-02-28 added: Client#organization_periodic_usages in lib/contentful/management/client.rb (lines 9-11), Client#space_periodic_usages in lib/contentful/management/client.rb (lines 23-25), ClientOrganizationPeriodicUsageMethodsFactory in lib/contentful/management/client_organization_periodic_usage_methods_factory.rb (lines 43-44), ClientSpacePeriodicUsageMethodsFactory in lib/contentful/management/client_space_periodic_usage_methods_factory.rb (lines 66-67), OrganizationPeriodicUsage in lib/contentful/management/organization_periodic_usage.rb (lines 89-90), and SpacePeriodicUsage in lib/contentful/management/space_periodic_usage.rb (lines 117-118).
MOI-7251	Emit runtime deprecation warnings for legacy usage endpoint calls in the Ruby SDK	✅ Met	All required entry-point and .all class methods emit runtime deprecation warnings: Client#organization_periodic_usages in lib/contentful/management/client.rb (lines 14-16) and Client#space_periodic_usages in lib/contentful/management/client.rb (lines 28-30) emit warn '[DEPRECATION]...' at call time. OrganizationPeriodicUsage.all in lib/contentful/management/organization_periodic_usage.rb (lines 102-104) and SpacePeriodicUsage.all in lib/contentful/management/space_periodic_usage.rb (lines 130-132) also emit warn '[DEPRECATION]...' messages at call time.
MOI-7251	Verify build and full test suite pass for the Ruby SDK deprecation changes	🟡 Partial	[Non-Diff Requirement] Build and test suite validation (bundle exec rspec and bundle exec rubocop) requires runtime execution and cannot be verified from the diff alone. The deprecation changes follow the established pattern from contentful-management.js and are syntactically correct.

[bito-code-review]

Impact Analysis by Bito

Interaction Diagram

sequenceDiagram
participant Dev as Developer
participant SDK as contentful-management.rb SDK<br/>🔄 Updated | ●●○ Medium
participant Client as Client<br/>🔄 Updated | ●●○ Medium
participant OrgFactory as ClientOrganizationPeriodicUsageMethodsFactory<br/>🔄 Updated | ●●○ Medium
participant ResFactory as ClientSpacePeriodicUsageMethodsFactory<br/>🔄 Updated | ●●○ Medium
participant OrgUsage as OrganizationPeriodicUsage<br/>🔄 Updated | ●●○ Medium
participant SpaceUsage as SpacePeriodicUsage<br/>🔄 Updated | ●●○ Medium
participant API as Contentful Management API
Note over Dev, API: Deprecation flow for legacy Usage API endpoints
Dev->>SDK: client.organization_periodic_usages(org_id)
SDK->>Client: organization_periodic_usages(organization_id)
Client->>Client: warn('[DEPRECATION] Legacy endpoint deprecated')
Client-->>SDK: Return ClientOrganizationPeriodicUsageMethodsFactory
SDK->>OrgFactory: all(params)
OrgFactory->>API: GET /organizations/&#123;id&#125;/organization_periodic_usages
alt alternative entrypoint
Dev->>SDK: OrganizationPeriodicUsage.all(client, org_id)
SDK->>OrgUsage: all(client, organization_id, params)
OrgUsage->>OrgUsage: warn('[DEPRECATION] Legacy endpoint deprecated')
OrgUsage->>OrgFactory: all(params)
OrgFactory->>API: GET /organizations/&#123;id&#125;/organization_periodic_usages
    end
API-->>OrgFactory: Return OrganizationPeriodicUsage array
OrgFactory-->>SDK: Return Array<OrganizationPeriodicUsage>
SDK-->>Dev: Usage data (until 2027-02-28)
Note over Dev: After 2027-02-28 API returns 410 Gone

Loading

---

This PR adds deprecation warnings to legacy usage API endpoints (organization_periodic_usages and space_periodic_usages) in the contentful-management.rb SDK. Warnings are emitted via `warn()` at the Client and Resource class levels, alerting developers that these endpoints will return 410 Gone after 2027-02-28 and should migrate to the new Usage API. No functional changes to API calls are made - deprecation is informational only.

Cross-Repository Impact Analysis

What Changed	Impact of Change	Suggested Review Actions
Added runtime deprecation warnings and Daniel Edeling (@deprecated) YARD documentation to four public API entry points: Client#organization_periodic_usages, Client#space_periodic_usages, OrganizationPeriodicUsage.all, SpacePeriodicUsage.all.	- No cross-repo consumers found for any deprecated symbol: searchCode returned zero_hits for all four primary symbol patterns (organization_periodic_usages, space_periodic_usages, OrganizationPeriodicUsage, SpacePeriodicUsage) across all indexed repositories. No other repos directly import or call these SDK methods.	- No cross-repo migration action required — no external consumers found in indexed org. - Ensure the new Usage API migration path is documented in the SDK README so downstream SDK consumers can migrate before 2027-02-28.

Code Paths Analyzed

Impact:
Runtime deprecation warnings are now emitted (via Ruby's warn) whenever any of the four deprecated APIs are called. The methods remain fully functional — no behavior change, only a warning side-effect. No API contract is broken; the deprecated endpoints still respond until 2027-02-28.

Flow:
Caller → Client#organization_periodic_usages or Client#space_periodic_usages → ClientXxxPeriodicUsageMethodsFactory → ResourceRequester → HTTP GET /organizations/:id/(space|organization)_periodic_usages (deprecated upstream API). The change injects a warn call at the entry point in client.rb and in the static all() methods on the two resource classes.

Direct Changes (Diff Files):
• lib/contentful/management/client.rb [141–167] — Added Daniel Edeling (@deprecated) YARD tag and runtime warn('[DEPRECATION]...') to Client#organization_periodic_usages and Client#space_periodic_usages methods.
• lib/contentful/management/client_organization_periodic_usage_methods_factory.rb [6–20] — Added Daniel Edeling (@deprecated) YARD tags to ClientOrganizationPeriodicUsageMethodsFactory class and its #all method.
• lib/contentful/management/client_space_periodic_usage_methods_factory.rb [6–20] — Added Daniel Edeling (@deprecated) YARD tags to ClientSpacePeriodicUsageMethodsFactory class and its #all method.
• lib/contentful/management/organization_periodic_usage.rb [6–106] — Added Daniel Edeling (@deprecated) YARD tag to OrganizationPeriodicUsage class and its self.all method; added runtime warn('[DEPRECATION]...') in self.all.
• lib/contentful/management/space_periodic_usage.rb [6–134] — Added Daniel Edeling (@deprecated) YARD tag to SpacePeriodicUsage class and its self.all method; added runtime warn('[DEPRECATION]...') in self.all.

Repository Impact:
• SDK public API surface (client.rb) + 4 resource/factory classes: All five files receive Daniel Edeling (@deprecated) documentation only; no implementation logic changes. The warning is non-fatal and does not affect return values or behavior.
• README.md usage examples (lines 939–968): README.md contains usage examples for the deprecated APIs (client.organization_periodic_usages, client.space_periodic_usages, organization.space_periodic_usages). These examples will now emit deprecation warnings. Reviewers should consider adding a note that these examples are deprecated or replacing them with new Usage API examples.

Cross-Repository Dependencies:
• No cross-repo dependencies detected: searchCode across all indexed repositories returned zero hits for all deprecated symbol patterns. BitoAIArchitect's repository index does not contain contentful-management.rb itself. This SDK is a client library — its public methods are consumed by application code, but no other repos in the org index call these specific deprecated methods.

Database/Caching Impact:
• None

API Contract Violations:
• No API contract violations. The change is purely additive — it adds a warning side effect but does not modify signatures, return types, or HTTP behavior. The underlying deprecated endpoints still function until 2027-02-28.

Infrastructure Dependencies:
• No CI/CD or infrastructure changes. Deprecation dates (2027-02-28) are stated in the warning messages and YARD tags — these should be aligned with the actual Contentful API sunset schedule.

Additional Insights:
• Deprecation notice clarity: The warning message says 'Migrate to the new Usage API' but does not link to documentation or specify the new API name/path. Users reading the warning have no actionable migration path. Consider adding a URL to the new Usage API docs.
• Upstream API sunset coupling: The 2027-02-28 removal date in the warning is hardcoded. If Contentful pushes this date, the SDK warning must be updated manually. Consider extracting the date to a constant or loading it from a version file.
• README examples: README.md still shows usage examples for both deprecated APIs (lines 939, 942, 958, 961, 968). While not changed in this diff, these examples will emit deprecation warnings when users run them. A follow-up README update to show the new Usage API equivalents is recommended.

Testing Recommendations

Frontend Impact:
• None.

Service Integration:
• Verify that the new Usage API (replacement endpoint) is accessible and documented. Confirm the deprecated endpoints still respond until 2027-02-28 so existing tests (VCR cassettes) do not break unexpectedly.

Data Serialization:
• None.

Privacy Compliance:
• None.

Backward Compatibility:
• All existing tests (spec/lib/contentful/management/organization_periodic_usage_spec.rb, spec/lib/contentful/management/space_periodic_usage_spec.rb) call the deprecated methods and should still pass. The warnings do not raise exceptions. Run the full spec suite with bundle exec rspec to confirm no regressions.
• If $VERBOSE is set to false (e.g., in production), warnings will be suppressed — confirm this is the intended behavior. The warn output does not interfere with return values.

OAuth Functionality:
• None

Reliability Testing:
• None

Additional Insights:
• Add a test specifically for deprecation warning output: expect { client.organization_periodic_usages(org_id) }.to output(/DEPRECATION/).to_stderr to ensure warnings fire correctly and don't regress.
• Consider adding a test for the Daniel Edeling (@deprecated) YARD tags on the resource classes and factory classes to ensure documentation completeness is maintained.
• Update README.md examples for organization_periodic_usages and space_periodic_usages to note they are deprecated and link to the new Usage API, or replace them with new Usage API examples.
• Align the 2027-02-28 removal date in the warning messages with Contentful's official API deprecation schedule — verify this date is accurate before merging.

_{Analysis based on known dependency patterns and edges. Actual impact may vary.}

[bito-code-review]

✅ Review Settings Overridden

Status: Overridden Successfully

Guidelines:

• Accepted:

  • General : Repo Truth And Alignment, Domain Invariants, Review Posture

Note: Extra guidelines beyond 3 general purpose guidelines and 1 language specific guideline per language are not processed. Guidelines are fetched from the source branch.