feat: Enhance billing and transaction handling

- Added methods to InvoiceRepositoryInterface for retrieving the latest, pending, and overdue invoices for a subscription.
- Introduced TransactionRepositoryInterface for managing transaction records.
- Created events for payment failures, successful payments, and refunds to facilitate better event-driven architecture.
- Implemented new methods in BillingService for handling invoice payments, failed payments, and refunds, ensuring proper state transitions and event dispatching.
- Updated Invoice and Transaction models to support new functionalities, including refund tracking.
- Added tests for invoice queries and transaction recording to ensure correctness of new features and idempotency of payment processing.

Author: Foysal50x

CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Transaction ledger API** — `BillingService::recordPayment()`,
+  `recordFailedPayment()`, and `recordRefund()` (via `Tashil::billing()`) record the
+  payments/refunds the host's gateway executes, each writing the `Transaction`
+  audit row **and** reflecting the invoice state in one DB transaction. Tashil
+  still never moves money — these only *record* what the host reports.
+  - `recordPayment()` writes a `success` transaction and marks the invoice paid
+    (routing through `InvoiceObserver` → activate / advancePeriod / reactivate).
+  - `recordFailedPayment()` writes a `failed` transaction and leaves the invoice
+    `Pending` for dunning.
+  - `recordRefund()` accumulates `refunded_amount` (partials supported); a full
+    refund flips the transaction to `Refunded` and the invoice to `Refunded`.
+  - `recordPayment` / `recordFailedPayment` are idempotent on
+    `UNIQUE(gateway, transaction_id)` — a replayed at-least-once webhook resolves
+    to the existing row and never double-settles.
+- **`TransactionRepositoryInterface` + `EloquentTransactionRepository`** — the
+  transaction ledger now sits behind an overridable repository like every other
+  persistence concern.
+- **Events** `PaymentRecorded`, `PaymentFailed`, `PaymentRefunded` — carry the
+  transaction + invoice, dispatched after commit.
+- **`Invoice::markAsRefunded()` / `Invoice::isRefunded()`** and a
+  `gateway_response` array cast on `Transaction`.
+- **Invoice/transaction read API** on `BillingService` (`Tashil::billing()`):
+  `latestInvoice($sub, ?InvoiceKind)`, `pendingInvoice($sub)`,
+  `overdueInvoice($sub)`, and `successfulTransaction($invoice)` — so host code
+  reads invoices through the (overridable) repository instead of querying the
+  `Invoice` model directly. Backed by new `InvoiceRepositoryInterface` methods
+  (`latestForSubscription`, `pendingForSubscription`, `overdueForSubscription`)
+  and `TransactionRepositoryInterface::latestSuccessfulForInvoice`; these read
+  paths are uncached (per-subscription invoices change on every payment/dunning
+  step).
+
+### Changed
+
+- Cookbook examples (`PaymentWebhookController`, `ChargeRenewalInvoice`,
+  `DunningListeners`) now use `recordPayment()` / `recordFailedPayment()` instead
+  of hand-written `Transaction::create()` + `markAsPaid()`; added a
+  `RefundController` example. `CheckoutController`, `TrialController`, and
+  `SuspensionController` now read invoices via the billing API instead of direct
+  `Invoice` queries. Billing docs document the ledger + refund flow and the read
+  API.
+
+### Fixed
+
+- **`TransactionIdGenerator` uniqueness is now scoped to the gateway.** It takes
+  the row's gateway via a new constructor argument (passed by
+  `TransactionObserver`) and checks the composite `(gateway, transaction_id)` —
+  matching the DB constraint — instead of the bare `transaction_id`. The old
+  global check wrongly rejected (and regenerated) an id that already existed
+  under a *different* gateway; the same id can legitimately exist per gateway.
+  Custom transaction generators may declare a `string $gateway` constructor
+  parameter to receive it.
+
 ## [1.0.0-beta] - 2026-06-05
 
 First public beta. Subscription + feature management for Laravel with an

CLAUDE.md

@@ -4,7 +4,7 @@ AI working guide for `foysal50x/tashil`. Read before touching code.
 
 ## What this package is
 
-Laravel subscription + feature management. **Owns** plan catalog, subscription state, feature gating, atomic usage counters, trial lifecycle, scheduled state transitions, invoice issuance, the **activate-on-payment → renewal → dunning → reactivation** state machine, **proration on in-place plan changes**, immutable event log, and route middleware for gating. **Does NOT own** payment capture, the actual retry *charge* during dunning, refund execution, gateway sync, or the wallet/balance that funds Metered features — host app handles money movement and binds `MeteredBilling` for metered billing. Read [docs/09-Billing-Lifecycle.md](docs/09-Billing-Lifecycle.md) before touching activation / renewal / dunning / proration code.
+Laravel subscription + feature management. **Owns** plan catalog, subscription state, feature gating, atomic usage counters, trial lifecycle, scheduled state transitions, invoice issuance, the **transaction ledger** (recording the payments/refunds the host executes), the **activate-on-payment → renewal → dunning → reactivation** state machine, **proration on in-place plan changes**, immutable event log, and route middleware for gating. **Does NOT own** payment capture, the actual retry *charge* during dunning, refund execution, gateway sync, or the wallet/balance that funds Metered features — host app handles money movement, reports the result via `Tashil::billing()->record*()`, and binds `MeteredBilling` for metered billing. Read [docs/09-Billing-Lifecycle.md](docs/09-Billing-Lifecycle.md) before touching activation / renewal / dunning / proration code.
 
 **Billing model:** a priced plan (`price > 0`, `requires_payment = true`) subscribes as `Pending` with NO access; an `initial` invoice is issued, and `activate()` runs when it's paid (anchoring the period to `paid_at`). Free / `requires_payment = false` plans subscribe `Active` immediately. Trials subscribe `OnTrial` (access granted) and bill at `convertTrial()`. Gating is decided by the **package's own `requires_payment` flag** — `tashil.billing.activate_on_payment` (default `true`) only seeds that flag at creation when the caller doesn't set it; flipping the config later affects only new packages. Create packages with `requires_payment = false` for the legacy "access first, bill on renewal" model.
 
@@ -178,6 +178,7 @@ Adding a feature ⇒ add a Feature test. Fixing a bug ⇒ add a regression test
 |---|---|
 | New subscription state transition | `SubscriptionService` method + `EventStore::append` + event class + state machine doc |
 | Activation / renewal / dunning / proration | `SubscriptionService` (`activate`/`reactivate`/`markPastDue`/`suspend`/`changePlan`), `InvoiceObserver` routing, `ProcessDunningCommand` + [docs/09-Billing-Lifecycle.md](docs/09-Billing-Lifecycle.md) |
+| Recording payments / refunds / failures | `BillingService` (`recordPayment`/`recordFailedPayment`/`recordRefund`), `Payment*` event, `TransactionRepositoryInterface`, `Invoice::markAs*` + [docs/09-Billing-Lifecycle.md](docs/09-Billing-Lifecycle.md) (Transaction ledger). Keep it record-only — no gateway calls |
 | New feature type | `FeatureType` enum + `FeatureBuilder::xxx()` helper + `Feature::isXxx()` + `UsageService::check`/`increment` + `EloquentSubscriptionRepository::syncFeatures` (limit_value rules) + doc 02 |
 | New scheduled job | `src/Console/` command + wire in `TashilServiceProvider::registerSchedule()` + doc 04 |
 | Custom invoice / transaction id | Implement `generate(): string` (extend `TokenizedIdGenerator` for token format reuse) + bind in `config/tashil.php` `invoice.generator` / `transaction.generator` |
@@ -189,16 +190,29 @@ Adding a feature ⇒ add a Feature test. Fixing a bug ⇒ add a regression test
 
 ```
 Tashil issues Invoice (status=pending) → fires InvoiceIssued
-Host listener charges via gateway → on success calls $invoice->markAsPaid()
+Host listener charges via gateway → on success calls
+  Tashil::billing()->recordPayment($invoice, gateway, transactionId)
+    → writes Transaction(status=success) + $invoice->markAsPaid()  (one DB tx)
 Tashil InvoiceObserver (status → Paid):
-  → SubscriptionService::advancePeriod($sub)
+  → SubscriptionService::advancePeriod($sub)   (or activate / reactivate, by kind+status)
   → EventStore::append('subscription.renewed')
   → dispatch SubscriptionRenewed + InvoicePaid
+→ BillingService dispatches PaymentRecorded (after commit)
 ```
 
-For dunning / webhook reconciliation / refunds, host wires equivalent listeners. Tashil ends at issuing the bill and reflecting the host's `markAsPaid` decision.
+For dunning / webhook reconciliation / refunds, host wires equivalent listeners. Tashil ends at issuing the bill and recording the host's reported result (payment / failure / refund); it never charges or refunds at the gateway.
 
-Transactions: pass gateway-supplied id through (`ch_…`, `txn_…`). `UNIQUE(gateway, transaction_id)` on `tashil_transactions` makes duplicate webhook deliveries safe — catch `UniqueConstraintViolationException` as "already recorded". For cash / manual entries, leave `transaction_id` empty — `TransactionObserver::creating` stamps `TXN-…` from `tashil.transaction.generator`.
+Transaction ledger: record money events through `Tashil::billing()` — don't hand-roll `Transaction::create()` + `markAsPaid()`:
+
+- `recordPayment($invoice, …)` → `success` txn + `markAsPaid()` (routes activate/advance/reactivate) + `PaymentRecorded`.
+- `recordFailedPayment($invoice, …)` → `failed` txn, invoice stays `Pending` for dunning + `PaymentFailed`.
+- `recordRefund($transaction, …)` → accumulates `refunded_amount`; full refund flips txn→`Refunded` + invoice→`Refunded` + `PaymentRefunded`. Records a host-executed gateway refund; never executes one.
+
+`recordPayment` / `recordFailedPayment` are idempotent on `UNIQUE(gateway, transaction_id)` — a replayed at-least-once webhook resolves to the existing row (no double-settle), so the host no longer hand-catches `UniqueConstraintViolationException`. Pass the gateway id (`ch_…`, `txn_…`) verbatim; leave it null for cash/manual entries and `TransactionObserver::creating` stamps `TXN-…` from `tashil.transaction.generator` (uniqueness checked within the row's gateway — `TransactionIdGenerator` takes the gateway via its constructor and checks the composite `(gateway, transaction_id)`, so the same id under a different gateway is allowed). The ledger sits behind `TransactionRepositoryInterface` (Eloquent default, append-only, uncached). `Invoice::markAsPaid/markAsVoid/markAsRefunded` remain as low-level transitions for hosts that record the transaction themselves.
+
+Invoice/transaction reads also go through `Tashil::billing()` — don't query the `Invoice` model directly in host code:
+- `latestInvoice($sub, ?InvoiceKind)`, `pendingInvoice($sub)` (outstanding), `overdueInvoice($sub)` (pending + past due), `successfulTransaction($invoice)` (the charge a refund targets).
+- These resolve through `InvoiceRepositoryInterface` / `TransactionRepositoryInterface` and are intentionally **not** cached (per-subscription invoices change on every payment/dunning step). New per-subscription invoice read ⇒ add to the interface + Eloquent + Cache decorator (pass-through), then expose on `BillingService`.
 
 ### Metered billing contract
 
@@ -255,9 +269,9 @@ Host overrides via `Tashil::resolveSubscribableUsing(fn () => Team::current())`
 
 ## Out of scope — don't add
 
-- Card capture, payouts, refund execution, gateway sync.
+- Card capture, payouts, refund **execution**, gateway sync. (Tahsil *records* payments/refunds the host already executed — `recordPayment` / `recordRefund` — but never calls a gateway. Keep `record*` a pure ledger + invoice-state reflection; don't add a gateway client, charge, or refund call here.)
 - The actual retry *charge* during dunning, and webhook reconciliation logic. (Tahsil owns the dunning *state machine + schedule* — `tashil:process-dunning` — and fires the events; the host performs the charge. Don't add charging here.)
-- Hash-chained financial ledger.
+- Hash-chained financial ledger. (The `tashil_transactions` ledger is a plain audit table, not a tamper-evident chain.)
 - Coupon / discount engine.
 - Wallet / balance / account ledger — Metered features delegate to host via `MeteredBilling`. Don't introduce balance tables here.
 - MRR waterfall (new/expansion/contraction/churn) beyond `AnalyticsService`.
@@ -287,7 +301,11 @@ Tashil::package('pro')->name('Pro')->price(29)->monthly()->trialDays(14)
 // Priced plan → Pending until the initial invoice is paid (then auto-activates).
 $sub = Tashil::subscription()->subscribe($user, $package);
 Tashil::subscription()->subscribe($user, $package, withTrial: true); // OnTrial, access now
-// Host charges → $invoice->markAsPaid() → InvoiceObserver → activate()
+// Host charges → Tashil::billing()->recordPayment($invoice, gateway, txnId) → InvoiceObserver → activate()
+
+Tashil::billing()->recordPayment($invoice, gateway: 'stripe', transactionId: 'ch_…'); // success txn + settle (idempotent)
+Tashil::billing()->recordFailedPayment($invoice, gateway: 'stripe');                   // failed txn; stays pending for dunning
+Tashil::billing()->recordRefund($transaction, amount: 12.50, reason: '…');             // host-executed refund; full → invoice Refunded
 
 Tashil::subscription()->convertTrial($sub);                      // anchors + first invoice
 Tashil::subscription()->changePlan($sub, $newPackage);           // in-place: upgrade prorates, downgrade defers

README.md

@@ -19,7 +19,7 @@ It **does not charge** — payment capture, dunning retries, refunds, and gatewa
 - [Subscriptions](#subscriptions)
 - [Feature System](#feature-system)
 - [Trial System](#trial-system)
-- [Invoices](#invoices)
+- [Invoices & transactions](#invoices--transactions)
 - [Scheduler](#scheduler)
 - [Events](#events)
 - [Analytics & Reporting](#analytics--reporting)
@@ -374,22 +374,42 @@ See [docs/03-Trial-System.md](docs/03-Trial-System.md).
 
 ---
 
-## Invoices
+## Invoices & transactions
 
-Tahsil issues invoices on subscribe (non-trial) and renewal. The host charges and marks them paid.
+Tahsil issues invoices on subscribe (non-trial) and renewal, and keeps a **transaction ledger** of the payments/refunds the host reports. The host moves the money; Tahsil records it and reflects the invoice state.
 
 ```php
 $invoice = Tashil::billing()->generateInvoice($subscription);
-// host charges via gateway, then:
-$invoice->markAsPaid();   // InvoiceObserver advances current_period_end
-                          // and dispatches SubscriptionRenewed + InvoicePaid
+
+// host charges via gateway, then records the result in ONE call:
+Tashil::billing()->recordPayment($invoice, gateway: 'stripe', transactionId: 'ch_…');
+// → writes a success Transaction + marks the invoice paid (InvoiceObserver
+//   advances/activates by kind) + fires PaymentRecorded & InvoicePaid.
+//   Idempotent on UNIQUE(gateway, transaction_id) — safe for replayed webhooks.
+
+// declined charge → audit only; invoice stays pending for dunning:
+Tashil::billing()->recordFailedPayment($invoice, gateway: 'stripe');
+
+// refund the host already executed at the gateway (full or partial):
+Tashil::billing()->recordRefund($transaction, amount: 12.50, reason: 'customer request');
+// → partial keeps Success/Paid; full flips Transaction→Refunded + Invoice→Refunded; fires PaymentRefunded.
+```
+
+Read invoices/transactions through the billing API instead of querying the `Invoice` model directly — the access path stays behind the (overridable) repository:
+
+```php
+Tashil::billing()->latestInvoice($subscription);                       // most recent invoice
+Tashil::billing()->latestInvoice($subscription, InvoiceKind::Initial); // most recent of a kind
+Tashil::billing()->pendingInvoice($subscription);                      // outstanding bill to pay (or null)
+Tashil::billing()->overdueInvoice($subscription);                      // pending + past due (or null)
+Tashil::billing()->successfulTransaction($invoice);                    // the settled charge a refund targets
 ```
 
-Invoice statuses: `draft`, `pending`, `paid`, `void`, `refunded`.
+`Invoice::markAsPaid()` / `markAsVoid()` / `markAsRefunded()` remain as low-level state transitions, but `recordPayment` / `recordRefund` are the complete, idempotent path (they also write the transaction row). Invoice statuses: `draft`, `pending`, `paid`, `void`, `refunded`. Transaction statuses: `pending`, `success`, `failed`, `refunded`.
 
 Invoice numbers are generated by `tashil.invoice.generator` — default `InvoiceNumberGenerator` parses the format string `#-YYMMDD-NNNNNN` (e.g. `INV-260522-849021`).
 
-Both built-in generators implement `Foysal50x\Tashil\Contracts\ShouldBeUnique` — they pre-check the rendered id against the live table (`invoice_number` / `transaction_id`) and re-render on a hit, bounded by `maxGenerationAttempts()` before throwing `UniqueIdGenerationException`. The pre-check only narrows the window; the DB unique constraint is the real guarantee under concurrency, and the host owns retry on an actual collision. Supply your own generator to change the uniqueness scope, or implement `generate()` without the contract to skip the check. See [docs/06-Developer-Guide.md › Guaranteed-unique ids](docs/06-Developer-Guide.md#guaranteed-unique-ids).
+Both built-in generators implement `Foysal50x\Tashil\Contracts\ShouldBeUnique` — they pre-check the rendered id against the live table (`invoice_number` globally; `TransactionIdGenerator` against the composite `(gateway, transaction_id)`, so the same id under a different gateway is allowed) and re-render on a hit, bounded by `maxGenerationAttempts()` before throwing `UniqueIdGenerationException`. The pre-check only narrows the window; the DB unique constraint is the real guarantee under concurrency, and the host owns retry on an actual collision. Supply your own generator to change the uniqueness scope, or implement `generate()` without the contract to skip the check. See [docs/06-Developer-Guide.md › Guaranteed-unique ids](docs/06-Developer-Guide.md#guaranteed-unique-ids).
 
 ---
 
@@ -434,6 +454,7 @@ All events dispatch after `DB::afterCommit()` so listeners never see torn state
 | `MeteredCharged` | Metered `useFeature()` charge accepted — carries units, unit price, amount, currency. |
 | `MeteredChargeRejected` | Metered charge declined (insufficient balance / provider refusal). |
 | `InvoiceIssued` / `InvoicePaid` / `InvoiceVoided` / `InvoiceOverdue` | Invoice lifecycle. |
+| `PaymentRecorded` / `PaymentFailed` / `PaymentRefunded` | Transaction ledger — `recordPayment()` / `recordFailedPayment()` / `recordRefund()`; carry the transaction + invoice. |
 
 Listen normally:
 

docs/01-DB-Schema.md

@@ -358,7 +358,7 @@ Optional ledger of gateway settlements linked to invoices. Tahsil itself never w
 | `id` | BIGINT PK | |
 | `invoice_id` | BIGINT FK | cascadeOnDelete |
 | `gateway` | VARCHAR | Defaults to `manual`. Identifies the payment source (e.g. `stripe`, `paddle`, `bkash`). |
-| `transaction_id` | VARCHAR NULL | Gateway-supplied id, or auto-generated by `TransactionObserver::creating` via `tashil.transaction.generator` when empty (e.g. cash collected by an admin). |
+| `transaction_id` | VARCHAR NULL | Gateway-supplied id, or auto-generated by `TransactionObserver::creating` via `tashil.transaction.generator` when empty (e.g. cash collected by an admin). Generated ids are made unique within their `gateway`, matching the composite constraint. |
 | `amount`, `currency`, `status` | | |
 | `gateway_response`, `metadata` | JSON NULL | |
 | `refunded_amount`, `refunded_at`, `refund_reason` | | |