Instruction Laravel Package

Product Decisions This Supports

• Build vs. buy for billing/pricing logic. This package lets the team avoid hand-rolling a pricing engine. The v0.2.2 release upgrades it from a convenience library to a financial-grade component, which changes the calculus: it is now credible for revenue-affecting paths, not just internal tooling.
• Monetization and wallet/credits roadmap. The Bavix Laravel Wallet integration plus per-item revenue accumulation makes prepaid credits, usage wallets, and metered billing feasible as first-class product features rather than bespoke work. This directly unblocks roadmap items around top-ups, balance-based access, and instruction-level revenue reporting.
• Pricing model flexibility. Deterministic, rule-based pricing with a service layer and DTOs means product can iterate on pricing rules (per-instruction, tiered, historical) without re-architecting persistence. Price history support enables grandfathering, promotional pricing, and audit trails.
• API contract decisions. The new dual representation (price/price_minor, total_amount/total_amount_minor) is a product-visible API decision: human-readable decimals for display/clients, integer minor units for computation and reconciliation. This should be reflected in public API docs and SDKs.
• Financial accuracy as a product requirement. Migrating to integer minor units with Brick Money removes float rounding risk. This is a risk-reduction decision that product should own explicitly, especially as revenue volume grows.
• Use cases: metered billing for services/instructions, prepaid wallet top-ups, revenue tracking per line item, historical price reporting, and any domain where "instructions" are billable units.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP and need instruction- or line-item-level pricing with revenue tracking.
• You require wallet, credit, or prepaid balance mechanics (Bavix Laravel Wallet is already a dependency, so align with that choice).
• You need financial-grade money handling (integer minor units, Brick Money) and auditable price history.
• You want a deterministic, rule-based pricing engine with clean separation between models, services, and DTOs, plus meaningful test coverage.
• You are comfortable owning a migration: v0.2.2 is a breaking release for anyone storing prices as floats.

Look elsewhere when:

• You are not on Laravel, or you cannot adopt Bavix Laravel Wallet as your wallet model.
• You need full invoicing, tax computation, multi-currency FX, dunning, or PCI-compliant payment processing — this package is a pricing/wallet engine, not a billing platform.
• You need multi-currency support; the release notes describe minor-unit handling but do not claim currency conversion or per-currency ledgers.
• You need out-of-the-box subscription/plan management; verify against your roadmap before committing.
• Your team cannot absorb the float-to-minor-units breaking change and migration of existing data.

Assessment note: No prior assessment existed. This is the baseline assessment, reflecting v0.2.2 as the first reviewed release.

How to Pitch It (Stakeholders)

For executives: This release turns a pricing helper into a financial-grade billing component. It introduces wallet-based revenue tracking and precise integer-based money handling (via Brick Money), which reduces rounding errors and reconciliation risk — the kind of defect that becomes expensive at scale. It also adds price history, enabling auditable pricing changes and grandfathering. The trade-off is a breaking change: existing float-based prices must be migrated to decimal strings or integer minor units. This is a one-time migration that buys durable correctness.

For engineering: v0.2.2 delivers the architecture we would otherwise build ourselves: models for wallet and persistence, services for pricing logic, DTOs for serialization, a deterministic rule-based engine, and full test coverage across wallet flows, pricing, API responses, and factories. The new API contract exposes both decimal and minor-unit fields, which is the right shape for clients. The breaking change is explicit — floats are no longer accepted; prices must be decimal strings for input or integer minor units for computation. Plan a migration for any stored price data and update API consumers to read the new _minor fields where precision matters.

Recommendation: Adopt for revenue-affecting pricing where Laravel and a wallet model are already in scope. Budget an engineering sprint for the float-to-minor-units migration and API field adoption. Re-evaluate if requirements expand into multi-currency, tax, or full invoicing, which are out of scope today.