MPT-20733 add mock API route example

[svazquezco]

🤖 AI-generated PR — Please review carefully.

Summary

• Add authenticated APIRouter examples to the mock app.
• Add mock agreement routes for retrieve, list, create, and sync flows.
• Keep agreement creation support scoped to the mock MPT API service.
• Add a mock installation token response so the account-scoped flow can run locally.

Testing

• make check
• make test

Closes MPT-20733

Release Notes

• Added authenticated API router example with agreement operation endpoints (retrieve, list, create, and sync)
• Implemented MockAgreementService providing agreement creation, retrieval, and batch listing operations
• Implemented MockInstallationService providing account token creation for account-scoped API flows
• Added AgreementSchema for validating agreement request payloads
• Introduced SyncAdobeAgreements mock use case demonstrating the sync flow with tracing support
• Registered API router in the mock application to expose account-scoped endpoints locally
• Agreement creation is restricted to the mock API service and not exposed through the SDK service layer

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces agreement operations to a mock API application. New schema contracts define agreement fields; mock services implement CRUD and token operations; API routes expose list, get, create, and sync endpoints; and a background sync workflow fetches and processes agreements with distributed tracing.

Changes

Agreement API and Sync Flow

Layer / File(s)	Summary
Agreement schema contract mock_app/api/schemas.py	AgreementSchema defines typed fields for agreement metadata, client, licensee, parameters, and product information.
Mock agreement and installation services mock_app/mocks/api_service.py	MockAgreementService implements create, get_all, and get_by_id returning deterministic test payloads; MockInstallationService implements create_token; both wired into ExtMPTAPIService initialization.
Agreement API route handlers mock_app/api/api_routes.py	Four route handlers: GET /agreements/{agreement_id} (with "not-found" error case), GET /agreements (with pagination and fixed total=10), POST /agreements (schema-validated creation), and POST /agreements/sync (triggers sync workflow).
Agreement sync workflow mock_app/sync/agreements.py, mock_app/sync/__init__.py	SyncAdobeAgreements.execute() fetches agreements with batch_size=5, iterates through results, and invokes _sync_agreement() for each ID with distributed span tracing.
Application router integration mock_app/app.py	Imports and registers the agreement router alongside the existing orders router.

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Jira Issue Key In Title	✅ Passed	✅ Found Jira issue key in the title: MPT-20733
Test Coverage Required	✅ Passed	PR modifies code files in mock_app/ and includes changes in tests/ folder (54 test files). Test coverage requirement is satisfied.
Single Commit Required	✅ Passed	The PR contains exactly one commit (6a4cdcf: "feat: add mock API route example"), meeting the single commit requirement.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

🧹 Nitpick comments (1)

mock_app/api/api_routes.py (1)

22-22: ⚡ Quick win

Replace type: ignore[attr-defined] with a typed service cast.

This keeps strict typing intact and removes suppression comments in the route handlers.

Proposed refactor

+from typing import cast
+
+from mock_app.mocks.api_service import ExtMPTAPIService
 from mock_app.api.schemas import AgreementSchema
 from mock_app.sync.agreements import SyncAdobeAgreements
 from mpt_extension_sdk import APIRouter
 from mpt_extension_sdk.api import APIContext, APIResponse, NotFoundError, PaginatedResult
@@
 async def handle_get_agreements(ctx: APIContext) -> APIResponse:
     """Return paginated mock agreements."""
-    agreements = await ctx.mpt_api_service.agreements.get_all(batch_size=3)  # type: ignore[attr-defined]
+    mpt_api_service = cast(ExtMPTAPIService, ctx.mpt_api_service)
+    agreements = await mpt_api_service.agreements.get_all(batch_size=3)
     result = PaginatedResult.from_pagination(ctx.request.pagination, payload=agreements, total=10)
     return APIResponse.paginated(result)
@@
 async def handle_create_agreement(body: AgreementSchema, ctx: APIContext) -> APIResponse:
     """Create one agreement through the mock service facade."""
-    new_agreement = await ctx.mpt_api_service.agreements.create(body)  # type: ignore[attr-defined]
+    mpt_api_service = cast(ExtMPTAPIService, ctx.mpt_api_service)
+    new_agreement = await mpt_api_service.agreements.create(body)
     return APIResponse.created(payload=new_agreement)

As per coding guidelines, new non-test Python code should type-check cleanly under strict mypy settings.

Also applies to: 30-30

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@mock_app/api/api_routes.py` at line 22, Replace the inline type ignore by
casting ctx.mpt_api_service to the concrete typed service (e.g., MPTApiService)
before calling agreements.get_all so mypy can verify members; import typing.cast
(or the service interface type) and use cast(MPTApiService, ctx.mpt_api_service)
(or assign to a typed variable) and then call agreements.get_all(batch_size=3)
on that typed object to remove the "# type: ignore[attr-defined]" suppression.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@mock_app/api/api_routes.py`:
- Line 22: Replace the inline type ignore by casting ctx.mpt_api_service to the
concrete typed service (e.g., MPTApiService) before calling agreements.get_all
so mypy can verify members; import typing.cast (or the service interface type)
and use cast(MPTApiService, ctx.mpt_api_service) (or assign to a typed variable)
and then call agreements.get_all(batch_size=3) on that typed object to remove
the "# type: ignore[attr-defined]" suppression.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: ba0bc4b6-e6a2-411c-9a41-dc94a07d86f4

📥 Commits

Reviewing files that changed from the base of the PR and between 827a773 and 6a4cdcf.

📒 Files selected for processing (6)

• mock_app/api/api_routes.py
• mock_app/api/schemas.py
• mock_app/app.py
• mock_app/mocks/api_service.py
• mock_app/sync/__init__.py
• mock_app/sync/agreements.py