feat: provisioning API endpoints and service documentation #32

Open

Charon wants to merge 2 commits from feat/docs-and-provisioning into dev

Charon commented

2026-03-24 16:35:16 +00:00

Member

Fixes #14
Fixes #15

Summary

Issue #14 (Service Documentation): Added comprehensive class-level PHPDoc to CreditNoteService, RefundService, SubscriptionService, CouponService, and InvoiceService — covering lifecycle state machines, design rationale, configuration references, and cross-references to related models/DTOs.
Issue #15 (Provisioning API): Implemented the provisioning API endpoints that were stubbed out in routes/api.php. Created ProductApiController (ping, product listing, product lookup by SKU) and EntitlementApiController (create, show, suspend, unsuspend, cancel, renew entitlements). Registered the commerce.api and commerce.matrix middleware aliases in Boot.php and activated the route group.

Test plan

Verify GET /api/v1/provisioning/ping returns 200 with Bearer token
Verify GET /api/v1/provisioning/products lists active products
Verify GET /api/v1/provisioning/products/{sku} returns product details
Verify POST /api/v1/provisioning/entitlements provisions a new entitlement
Verify suspend/unsuspend/cancel/renew lifecycle endpoints
Verify requests without Bearer token return 401
Confirm existing test suite is unaffected (pre-existing failures only)

🤖 Generated with Claude Code

Fixes #14 Fixes #15 ## Summary - **Issue #14 (Service Documentation):** Added comprehensive class-level PHPDoc to `CreditNoteService`, `RefundService`, `SubscriptionService`, `CouponService`, and `InvoiceService` — covering lifecycle state machines, design rationale, configuration references, and cross-references to related models/DTOs. - **Issue #15 (Provisioning API):** Implemented the provisioning API endpoints that were stubbed out in `routes/api.php`. Created `ProductApiController` (ping, product listing, product lookup by SKU) and `EntitlementApiController` (create, show, suspend, unsuspend, cancel, renew entitlements). Registered the `commerce.api` and `commerce.matrix` middleware aliases in `Boot.php` and activated the route group. ## Test plan - [ ] Verify `GET /api/v1/provisioning/ping` returns 200 with Bearer token - [ ] Verify `GET /api/v1/provisioning/products` lists active products - [ ] Verify `GET /api/v1/provisioning/products/{sku}` returns product details - [ ] Verify `POST /api/v1/provisioning/entitlements` provisions a new entitlement - [ ] Verify suspend/unsuspend/cancel/renew lifecycle endpoints - [ ] Verify requests without Bearer token return 401 - [ ] Confirm existing test suite is unaffected (pre-existing failures only) 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Charon added 2 commits 2026-03-24 16:35:16 +00:00

security: add CSRF protection to API billing endpoints 5bce748a0f

- Add `verified` middleware to billing route group so only
  email-verified users can access billing endpoints
- Separate read-only GET routes from state-changing POST routes
- Add `throttle:6,1` rate limiting to state-changing endpoints
  (cancel, resume, upgrade/preview, upgrade) — 6 requests per minute
- Reorganise route group with clear section comments

Fixes #13

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: provisioning API endpoints and service documentation 0685429c74

Implement the provisioning API endpoints referenced in routes/api.php
and add comprehensive PHPDoc to service classes missing documentation.

Provisioning API (Issue #15):
- ProductApiController: ping, product listing, product lookup by SKU
- EntitlementApiController: create, show, suspend, unsuspend, cancel, renew
- Uncomment and activate provisioning route group with commerce.api middleware
- Register commerce.api and commerce.matrix middleware aliases in Boot.php

Service documentation (Issue #14):
- CreditNoteService: lifecycle, FIFO ordering, state machine
- RefundService: gateway orchestration, eligibility, transaction safety
- SubscriptionService: lifecycle, proration, fixed-day billing periods
- CouponService: sanitisation, validation, Orderable polymorphism
- InvoiceService: PDF generation, storage, email delivery

Fixes #14
Fixes #15

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin feat/docs-and-provisioning:feat/docs-and-provisioning

git checkout feat/docs-and-provisioning

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git checkout dev

git merge --no-ff feat/docs-and-provisioning

git checkout feat/docs-and-provisioning

git rebase dev

git checkout dev

git merge --ff-only feat/docs-and-provisioning

git checkout feat/docs-and-provisioning

git rebase dev

git checkout dev

git merge --no-ff feat/docs-and-provisioning

git checkout dev

git merge --squash feat/docs-and-provisioning