release/v0.1.17-phase17-credit-packs

[menvil]

Phase 17 — Credit Packs

This release adds one-time credit pack purchases on top of the existing Cashier/CreditLedger architecture.

What's included (CONV-257 → CONV-273)

Foundation

• CreditPack enum (small, medium, large)
• config/billing.php with credit_packs (label, credits, stripe_price_id, description)
• CreditPackDto — immutable DTO with fromConfig() factory
• CreditPackRepository — all(), find(), findOrFail(), findByStripePriceId()

Checkout

• CreditPackCheckoutGateway interface + CashierCreditPackCheckoutGateway + FakeCreditPackCheckoutGateway
• BillingPaymentService::createCreditPackCheckout() — validates price ID, delegates to gateway, no immediate credit grant
• POST /billing/credits/{pack} route → CreditPackCheckoutController
• /billing/credits/success and /billing/credits/cancel redirect pages

Webhook Grant

• CreditPackWebhookHandler::handleCheckoutSessionCompleted() — extracts user/pack from metadata, grants credits via CreditLedger
• Idempotency via metadata_json->stripe_checkout_session_id check — same session never grants twice
• Full metadata stored: pack_key, pack_credits, stripe_event_id, stripe_checkout_session_id, stripe_payment_intent_id, stripe_price_id
• CashierWebhookController extends Cashier's controller with handleCheckoutSessionCompleted

UI

• <x-billing.buy-credits-cta> component (full and compact variants)
• Buy Credits CTA in user dropdown credits section
• Buy Credits CTA in conversion insufficient credits error state

What's NOT included (intentionally)

• Full billing page (Phase 18)
• Invoice history, payment methods, Customer Portal
• Subscription changes
• Credit expiration
• Team balances

Test results

• 486 tests, all passing
• composer lint passes
• npm run build passes

🤖 Generated with Claude Code

---

Summary by cubic

Adds one-time credit pack purchases with Stripe via laravel/cashier, including checkout, webhook-based credit grants, and “Buy credits” CTAs. Implements Phase 17 — Credit Packs (CONV-257 → CONV-273) and hardens webhook delivery with CSRF exemption and row-level locking.

• New Features

  • Config-driven credit packs in config/billing.php (small, medium, large) with label, credits, stripe_price_id, and description; CreditPackDto and CreditPackRepository.
  • Checkout: BillingPaymentService::createCreditPackCheckout, CreditPackCheckoutGateway with CashierCreditPackCheckoutGateway, POST /billing/credits/{pack}, and success/cancel pages.
  • Webhooks: custom /stripe/webhook via CashierWebhookController; CreditPackWebhookHandler grants credits via CreditLedger, ensures idempotency by metadata_json->stripe_checkout_session_id, locks CreditAccount before the check to prevent double-grants on concurrent Stripe retries, and stores Stripe metadata (stripe_event_id, stripe_checkout_session_id, stripe_payment_intent_id, stripe_customer_id, stripe_price_id, plus pack info). Prefers payload price_id over config fallback. CSRF is disabled for /stripe/webhook.
  • UI: <x-billing.buy-credits-cta> component; shown in the user dropdown and when a conversion fails due to low credits; error shows required credits and current balance. Resets the insufficient-credits state between steps to avoid stale errors. CTA links to /billing and uses var(--ca-on-primary) text color token.
  • Cashier routing: Cashier::ignoreRoutes() with our own webhook route.

• Migration

  • Set env vars: STRIPE_CREDIT_PACK_SMALL_PRICE_ID, STRIPE_CREDIT_PACK_MEDIUM_PRICE_ID, STRIPE_CREDIT_PACK_LARGE_PRICE_ID.
  • Configure Stripe to POST checkout.session.completed to /stripe/webhook.
  • Deploy config changes and reload config cache if used.

^{Written for commit 1a013b6. Summary will update on new commits.}

Summary by CodeRabbit

Release Notes

• New Features
  • Added credit pack purchasing system with three tier options
  • Added "Buy credits" call-to-action in user dropdown and during conversion workflows
  • Integrated Stripe payment gateway for secure credit purchases
  • Added purchase success and cancellation confirmation pages
  • Enhanced insufficient credits error messaging with integrated purchase prompts

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a complete credit pack purchasing feature: environment configuration for three Stripe price IDs, a new CreditPackDto and enum to represent small/medium/large tiers, a checkout gateway abstraction with Cashier implementation, a checkout controller and routes, Stripe webhook handling with idempotency protection and credit ledger integration, and UI components displaying buy-credits CTAs in insufficient-credit scenarios.

Changes

Credit pack checkout and webhook handling

Layer / File(s)	Summary
Credit pack data structures and configuration app/Enums/Billing/CreditPack.php, app/Data/Billing/CreditPackDto.php, config/billing.php, .env.example, tests/Unit/Billing/CreditPack*, tests/Feature/Billing/CreditPacksConfigTest.php	Introduces CreditPack enum and CreditPackDto with fromConfig() factory validation for required keys; adds config/billing.php sourcing Stripe price IDs from STRIPE_CREDIT_PACK_*_PRICE_ID environment variables.
Credit pack repository app/Services/Billing/CreditPackRepository.php, tests/Unit/Billing/CreditPackRepositoryTest.php	Repository exposes all(), find(key), findOrFail(key), and findByStripePriceId(stripePriceId) methods to look up credit packs from configuration as DTO instances.
Checkout gateway contracts and implementations app/Billing/Gateway/CreditPackCheckoutGateway.php, app/Billing/Gateway/CashierCreditPackCheckoutGateway.php, app/Billing/Gateway/FakeCreditPackCheckoutGateway.php, app/Providers/AppServiceProvider.php	New CreditPackCheckoutGateway interface with Cashier-backed implementation creating sessions via user->checkout(stripePriceId) with pack metadata; fake implementation for testing; service provider binds interface to implementations via Cashier::ignoreRoutes().
Payment service credit pack integration app/Billing/BillingPaymentService.php, tests/Feature/Billing/BillingPaymentServiceCreditPackTest.php	BillingPaymentService accepts credit-pack gateway, exposes createCreditPackCheckout() validating stripePriceId presence and delegating to gateway; tests verify successful checkout and validation errors.
Checkout controller, routes, and CSRF configuration app/Http/Controllers/Billing/CreditPackCheckoutController.php, routes/web.php, bootstrap/app.php, resources/views/billing/credits-success.blade.php, resources/views/billing/credits-cancel.blade.php, tests/Feature/Billing/CreditPackCheckoutRouteTest.php, tests/Feature/Billing/CreditPackRedirectPagesTest.php	CreditPackCheckoutController::__invoke resolves packs via repository and initiates checkout; routes register POST /billing/credits/{pack} and success/cancel views; CSRF middleware exempts stripe/webhook; tests verify auth requirements, redirects, and 404 behavior.
Stripe webhook event handling and credit granting app/Billing/Webhooks/CreditPackWebhookHandler.php, app/Http/Controllers/Billing/CashierWebhookController.php, tests/Support/FakeStripeEvents.php, tests/Feature/Billing/CreditPackWebhookHandlerTest.php, tests/Feature/Billing/CashierWebhookRouteTest.php, tests/Unit/Billing/CreditPackWebhookHandlerSkeletonTest.php, tests/Pest.php	Handler processes checkout.session.completed events: extracts metadata, validates user/pack, locks CreditAccount row, checks CreditTransaction JSON metadata for duplicate stripe_checkout_session_id to prevent double-crediting, and grants credits via CreditLedger->grant() with Stripe identifiers. Controller delegates to handler; tests verify credit granting, metadata persistence, idempotency across duplicate events and same-session different-event scenarios.
UI components and user-facing error handling resources/views/components/billing/buy-credits-cta.blade.php, resources/views/components/user-dropdown.blade.php, app/Livewire/Dashboard/DashboardConverter.php, resources/views/livewire/dashboard/dashboard-converter.blade.php, tests/Feature/ViewComponents/BuyCreditsCtaTest.php, tests/Feature/Dashboard/UserDropdownBuyCreditsTest.php, tests/Feature/Livewire/DashboardConverterCreditsTest.php	New buy-credits-cta component with variant prop (compact/full); user dropdown wraps balance and CTA in flex row; DashboardConverter adds $hasInsufficientCredits state flag, resets it before conversion attempts, catches InsufficientCreditsException with detailed balance-inclusive error message, and sets flag true; template conditionally renders compact CTA on insufficient-credits error.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• menvil/FileConverter#183: Introduces credit ledger infrastructure (CreditLedger->grant(), CreditAccount, CreditTransaction models) that this PR's webhook handler directly depends on to grant credits on checkout completion.
• menvil/FileConverter#223: Adds BillingPaymentService::createSubscriptionCheckout(); this PR extends the same service with createCreditPackCheckout() alongside existing subscription behavior.
• menvil/FileConverter#205: Both modify DashboardConverter insufficient-credits error handling; this PR adds $hasInsufficientCredits state and buy-credits CTA, while the related PR adds cost estimation and specialized exception messaging in the same conversion flow.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title is a version release identifier that does not meaningfully describe the primary feature being implemented (credit packs).	Consider using a descriptive title like 'Add credit pack one-time purchases with Stripe integration' that clearly summarizes the main feature being added.
Docstring Coverage	⚠️ Warning	Docstring coverage is 13.04% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release/v0.1.17-phase17-credit-packs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cubic-dev-ai]

3 issues found across 34 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="routes/web.php">

<violation number="1" location="routes/web.php:10">
P0: Stripe webhook POST route not excluded from CSRF protection. Stripe sends webhooks without CSRF tokens, so every incoming event will be rejected with HTTP 419 before reaching the handler. Credit pack purchases via Stripe Checkout will never trigger credit grants in production.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P0: Stripe webhook POST route not excluded from CSRF protection. Stripe sends webhooks without CSRF tokens, so every incoming event will be rejected with HTTP 419 before reaching the handler. Credit pack purchases via Stripe Checkout will never trigger credit grants in production.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At routes/web.php, line 10:

<comment>Stripe webhook POST route not excluded from CSRF protection. Stripe sends webhooks without CSRF tokens, so every incoming event will be rejected with HTTP 419 before reaching the handler. Credit pack purchases via Stripe Checkout will never trigger credit grants in production.</comment>

<file context>
@@ -1,10 +1,15 @@
 use App\Http\Controllers\ProfileController;
 use Illuminate\Support\Facades\Route;
 
+Route::post('/stripe/webhook', [CashierWebhookController::class, 'handleWebhook'])
+    ->name('cashier.webhook');
+
</file context>

[menvil]

@CodeRabbit review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

resources/views/components/billing/buy-credits-cta.blade.php (1)

10-10: ⚡ Quick win

Replace the hardcoded button text color with a RateGuru token.

text-white introduces a raw Tailwind color utility in a reusable component. Please switch this to the design-token-backed text color used for primary CTAs instead of hardcoding white here. As per coding guidelines, "Reusable UI components must use RateGuru tokens and must not introduce random Tailwind color utilities unless the deviation is documented in docs/design/design-contract.md".

🤖 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 `@resources/views/components/billing/buy-credits-cta.blade.php` at line 10, The
anchor in the buy-credits-cta component currently uses the raw Tailwind utility
text-white; remove that utility and replace it with the RateGuru design-token
for primary CTA text (e.g., the token-backed class used across the codebase such
as text-rg-on-primary or the equivalent token variable like
color:var(--rg-on-primary)), updating the class list on the <a> element and/or
the inline style accordingly; if your codebase does not yet expose a token
class, use the CSS variable (var(--rg-on-primary)) and add a TODO to replace
with the canonical token class, and document any deviation in
docs/design/design-contract.md.

🤖 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.

Inline comments:
In `@app/Billing/Webhooks/CreditPackWebhookHandler.php`:
- Around line 61-68: In the meta array inside CreditPackWebhookHandler (where
'stripe_price_id' is set), read the price id from the webhook payload (e.g.
$event['data']['object']['metadata']['price_id'] or similar on the fake event)
and use that value for 'stripe_price_id', falling back to $pack->stripePriceId
only when the payload value is null/empty; update the assignment so it prefers
the payload price id but retains the existing config value as a fallback.

In `@app/Livewire/Dashboard/DashboardConverter.php`:
- Line 67: Reset the insufficient-credit state whenever the user leaves or
re-enters the convert step and when the flow is restarted by clearing
$hasInsufficientCredits alongside convertError; locate the DashboardConverter
Livewire component and update the step-change handler(s) and the flow reset
method (the same places that currently reset convertError—refer to the convert()
method, the step navigation logic, and the flow restart/reset method) to set
$hasInsufficientCredits = false whenever convertError is cleared or the active
step changes away from or into the convert step.

---

Nitpick comments:
In `@resources/views/components/billing/buy-credits-cta.blade.php`:
- Line 10: The anchor in the buy-credits-cta component currently uses the raw
Tailwind utility text-white; remove that utility and replace it with the
RateGuru design-token for primary CTA text (e.g., the token-backed class used
across the codebase such as text-rg-on-primary or the equivalent token variable
like color:var(--rg-on-primary)), updating the class list on the <a> element
and/or the inline style accordingly; if your codebase does not yet expose a
token class, use the CSS variable (var(--rg-on-primary)) and add a TODO to
replace with the canonical token class, and document any deviation in
docs/design/design-contract.md.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 44631c54-a5e6-4177-bc63-d37508f6bc5d

📥 Commits

Reviewing files that changed from the base of the PR and between e544ed3 and fcaf705.

📒 Files selected for processing (36)

• .env.example
• app/Billing/BillingPaymentService.php
• app/Billing/Gateway/CashierCreditPackCheckoutGateway.php
• app/Billing/Gateway/CreditPackCheckoutGateway.php
• app/Billing/Gateway/FakeCreditPackCheckoutGateway.php
• app/Billing/Webhooks/CreditPackWebhookHandler.php
• app/Data/Billing/CreditPackDto.php
• app/Enums/Billing/CreditPack.php
• app/Http/Controllers/Billing/CashierWebhookController.php
• app/Http/Controllers/Billing/CreditPackCheckoutController.php
• app/Livewire/Dashboard/DashboardConverter.php
• app/Providers/AppServiceProvider.php
• app/Services/Billing/CreditPackRepository.php
• bootstrap/app.php
• config/billing.php
• resources/views/billing/credits-cancel.blade.php
• resources/views/billing/credits-success.blade.php
• resources/views/components/billing/buy-credits-cta.blade.php
• resources/views/components/user-dropdown.blade.php
• resources/views/livewire/dashboard/dashboard-converter.blade.php
• routes/web.php
• tests/Feature/Billing/BillingPaymentServiceCreditPackTest.php
• tests/Feature/Billing/CashierWebhookRouteTest.php
• tests/Feature/Billing/CreditPackCheckoutRouteTest.php
• tests/Feature/Billing/CreditPackRedirectPagesTest.php
• tests/Feature/Billing/CreditPackWebhookHandlerTest.php
• tests/Feature/Billing/CreditPacksConfigTest.php
• tests/Feature/Dashboard/UserDropdownBuyCreditsTest.php
• tests/Feature/Livewire/DashboardConverterCreditsTest.php
• tests/Feature/ViewComponents/BuyCreditsCtaTest.php
• tests/Pest.php
• tests/Support/FakeStripeEvents.php
• tests/Unit/Billing/CreditPackDtoTest.php
• tests/Unit/Billing/CreditPackEnumTest.php
• tests/Unit/Billing/CreditPackRepositoryTest.php
• tests/Unit/Billing/CreditPackWebhookHandlerSkeletonTest.php