Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
7f76fad
build: depend on the Lunar alpha.9 split packages instead of the mono…
alecritson Nov 12, 2026
3965831
refactor(payments): reconcile intents through ReconcilesPaymentIntents
alecritson Nov 12, 2026
39d5907
refactor(payments): treat RequiresAction and Processing intents as pe…
alecritson Nov 12, 2026
bbf7997
refactor(payments): read the client secret from the intent's client p…
alecritson Nov 12, 2026
0dfd712
refactor(payments): verify and adjust holds through the intent snapshot
alecritson Nov 12, 2026
38b419b
refactor(validation): register PickupPointRequired through the Steps …
alecritson Nov 12, 2026
b09a38a
refactor(shipping): read core's pickup option after the collection re…
alecritson Nov 12, 2026
a4be6f0
fix(payments): pin payment amounts from a fresh cart calculation
alecritson Nov 12, 2026
27e3bc2
test: pin the stale-draft session from the driver snapshot
alecritson Nov 12, 2026
cfdc7b9
fix(driver): eager-load line purchasables on the session's cart
alecritson Nov 12, 2026
e2d5854
test: use the array mailer in the test environment
alecritson Nov 12, 2026
ffdaa5e
test: give the route test storefront context a default language
alecritson Nov 12, 2026
db64e4c
fix(payments): reopen a session whose intent has waited on the custom…
alecritson Nov 12, 2026
c5f7d69
fix(payments): size refunds and captures in the session's pinned curr…
alecritson Nov 12, 2026
f970f91
fix(payments): reconcile sessions whose cart was pruned
alecritson Nov 12, 2026
dd4fa33
docs(spec): use the alpha.9 pickup, steps and payment intent names
alecritson Nov 12, 2026
5abc120
test: drop the duplicated order-create validator registration test
alecritson Nov 12, 2026
eede84f
fix(fulfilment): eager-load line purchasables before resolving shippi…
alecritson Nov 12, 2026
0e156a8
fix(payments): decide method availability on fresh totals at pay and …
alecritson Nov 12, 2026
8d8afc0
test(payments): pin the driver's pay gate and completion verify to fr…
alecritson Nov 12, 2026
ed0bd7f
fix(payments): snapshot the cart before locking the session in the ga…
alecritson Nov 12, 2026
3f9f38d
fix(checkout): return a recalculated snapshot from associateCustomer
alecritson Nov 12, 2026
3468f8a
docs(contracts): say that snapshot() writes the cart's totals cache
alecritson Nov 12, 2026
4c07359
fix(driver): pass the intent to authorize() under the reference key c…
alecritson Nov 12, 2026
910f3fb
fix(payments): answer a gateway that refuses to resize the intent at pay
alecritson Nov 12, 2026
d0ada7e
fix(checkout): reopen the session when the customer returns from a fa…
alecritson Nov 12, 2026
16fb30c
fix(payments): void an intent that waited on the customer too long be…
alecritson Nov 12, 2026
16f9f84
fix(payments): never complete a payment whose money already went back
alecritson Nov 12, 2026
52f610d
fix(payments): never refund an order the gateway placed before its su…
alecritson Nov 12, 2026
2a8e743
fix(payments): leave the listener's copy of the session as read when …
alecritson Nov 12, 2026
2892202
docs(checkout): say that the failed-redirect release relies on an und…
alecritson Nov 12, 2026
a7e275b
style: return the rejection-copy docblock to its method
alecritson Nov 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 0 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -342,17 +342,6 @@ composer test # pest + phpstan
vendor/bin/pint # code style
```

While Lunar v2 is in alpha, `lunarphp/core` on Packagist can lag behind the
contracts this package builds against. To test against a local monorepo
checkout, point Composer at it (not committed, both paths are local to you):

```bash
composer config repositories.lunar '{"type":"path","url":"../lunar/packages/core","options":{"symlink":true}}'
composer require "lunarphp/core:2.x-dev" -W
```

Revert with `git checkout -- composer.json && composer update lunarphp/core`.

### Known follow-ups

- The suite runs serially in CI. Two files reach for helpers and fake gateway
Expand Down
10 changes: 3 additions & 7 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,22 +20,18 @@
"homepage": "https://lunarphp.io/"
}
],
"repositories": [
{
"type": "vcs",
"url": "https://github.com/lunarphp/lunar"
}
],
"require": {
"php": "^8.4",
"inertiajs/inertia-laravel": "^2.0|^3.0",
"lunarphp/core": "^2.0@dev",
"lunarphp/lunarmono": "dev-checkout-deps as 2.x-dev",
"spatie/laravel-data": "^4.23"
},
"require-dev": {
"larastan/larastan": "^3.0",
"laravel/pint": "1.29.0",
"lunarphp/panel": "^2.0@alpha",
"lunarphp/stripe": "^2.0@alpha",
"lunarphp/table-rate-shipping": "^2.0@alpha",
"mockery/mockery": "^1.6.9",
"orchestra/testbench": "^10.0|^11.0",
"pestphp/pest": "^3.0|^4.0",
Expand Down
8 changes: 8 additions & 0 deletions config/checkout.php
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,14 @@
// webhook-less fallback. Small enough that a stuck customer is not
// stuck, large enough not to race the immediate post-confirm webhook.
'on_view_after_seconds' => 5,

// How long (minutes, aged on the pin) an intent may wait on the
// customer before it is voided and the session reopens for a retry
// on a fresh intent. A declined card and an abandoned 3-D Secure
// challenge both read as waiting on the customer and neither settles
// on its own, so without this the cart stays locked. Long enough to
// finish a challenge or a bank redirect.
'requires_action_minutes' => 30,
],

/*
Expand Down
2 changes: 1 addition & 1 deletion phpunit.xml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
<env name="DB_CONNECTION" value="testing"/>
<env name="APP_KEY" value="base64:2fl+Ktvkfl+Fuz4Qp/A75G2RTiWVA/ZoKZvp6fiiM10="/>
<env name="APP_ENV" value="testing"/>
<env name="MAIL_MAILER" value="log"/>
<env name="MAIL_MAILER" value="array"/>
<env name="LUNAR_TESTING_REPLACE_MODELS" value="false"/>
</php>
<source>
Expand Down
8 changes: 4 additions & 4 deletions spec/0000-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ lunar/checkout Everything checkout. The element model: capability interfaces
elements/gateways contribute Vue UI via runtime chunks, no rebuild (0009).
│
├── lunar/core The seams checkout rides: the cart API (Cart::set*), ShippingManifest,
│ Payments/AbstractPayment — plus ONE addition, the SupportsPaymentIntents
│ Payments/AbstractPayment, plus ONE addition, the ReconcilesPaymentIntents
│ capability contract (fetch/void/refund by intent) gateway drivers adopt
│ for the integrity protocol (0010). No checkout code.
│
Expand Down Expand Up @@ -91,7 +91,7 @@ client.
| 0009 | Frontend element extension | How third-party elements/gateways contribute Vue UI into the prebuilt app at runtime — `CheckoutAssets` registry, contributed ES-module chunks served same-origin, shared Vue + SDK via `window.Vue`/`window.Lunar` externals, build preset, version/fallback; first-party gateways prebuilt |
| 0006 | Worked example (guide) | End-to-end walkthrough of one reference checkout through the Inertia spine — element impl, registration, session, DTO, Vue render, payment method, completion. Illustrative, not normative |
| 0007 | Discount element | Resolves 0001's open question: discount is a `Summary`-region `CapturesData` element; adds an additive `Cart::setCoupon()` so it persists through the cart API |
| 0010 | Cart–session reconciliation | Backend-neutral session data model (no Lunar FKs; store only non-derivable); the full `CheckoutDriver` store/read surface; element bag; **driver-owned fingerprint + sync-while-Open + pin-and-confirm-at-pay** integrity with the completion re-verify + refund invariant; void-first invalidation on every terminalizing transition; one-active-session-per-cart via guarded unique-column concurrency; the `SupportsPaymentIntents` gateway seam; bounded `PaymentProcessing` reconciliation + stall protocol; lifecycle events |
| 0010 | Cart–session reconciliation | Backend-neutral session data model (no Lunar FKs; store only non-derivable); the full `CheckoutDriver` store/read surface; element bag; **driver-owned fingerprint + sync-while-Open + pin-and-confirm-at-pay** integrity with the completion re-verify + refund invariant; void-first invalidation on every terminalizing transition; one-active-session-per-cart via guarded unique-column concurrency; the `ReconcilesPaymentIntents` gateway seam; bounded `PaymentProcessing` reconciliation + stall protocol; lifecycle events |

### Cross-cutting decisions (apply to all specs)

Expand Down Expand Up @@ -155,7 +155,7 @@ client.
landing; future breaking changes require a spec + Rector rule per the package rule.
- The checkout concern lives in its own `packages/checkout` sub-package (`Lunar\Checkout\…`), not
a new core `Checkout/` folder — core's spec-0013 list is untouched; core gains only the
`SupportsPaymentIntents` capability contract (`Contracts/`, additive).
`ReconcilesPaymentIntents` capability contract (`Contracts/`, additive).
- Depends on the planned `public_id` (ULID) and Region/`StorefrontContext` TODO items; until they
land, cart identity stays resolved server-side via `CartSession` and the country list stays
channel-scoped.
Expand Down Expand Up @@ -184,7 +184,7 @@ client.
([[0008-checkout-ui-and-theming]]). It is **not** embedded into a consumer's Vue build;
any storefront stack links to it. `storefront-ui` is a reference host with it installed. The
Lunar-hosted page ([[0005-hosted-checkout]]) is the same app under a Lunar-operated deployment.
Core gains only the `SupportsPaymentIntents` capability contract.
Core gains only the `ReconcilesPaymentIntents` capability contract.
- A transport-free **`checkout-core` split** (element model + session + driver, no Inertia/Vue) so
a REST-only consumer (`lunar/api`) need not depend on the Inertia app package — recorded as an
open question, not done now. (Owner: package maintainer.)
Expand Down
2 changes: 1 addition & 1 deletion spec/0001-core-element-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ the configured validators and `recalculate()`:
| Element | Write path |
|---------|-----------|
| `ContactInformation` | `$context->storeContact($validated)` → (driver) `storeContact` — guest email/phone ([[0010-cart-session-reconciliation]] §B); contact is **not** an address write |
| `AddressElement` | `$context->storeShippingAddress($validated)` / `storeBillingAddress($validated)` → (driver) → `Cart::setShippingAddress()` / `setBillingAddress()` (→ `AddAddress` action, `lunar.cart.validators.add_address`, tax-zone clear, recalc) |
| `AddressElement` | `$context->storeShippingAddress($validated)` / `storeBillingAddress($validated)` → (driver) → `Cart::setShippingAddress()` / `setBillingAddress()` (→ `AddAddress` action, the `StepList::AddAddressValidation` steps, tax-zone clear, recalc) |
| `ShippingOptionsElement` | `$context->setShippingOption($identifier)` → (driver) resolves via `ShippingManifest::getOption($cart, $identifier)` → `Cart::setShippingOption($option)` (→ `SetShippingOption` action + validator + recalc); persists identifier only |

Direct `fill()->save()` is forbidden: it bypasses the validators and the recalculation, letting
Expand Down
22 changes: 13 additions & 9 deletions spec/0002-payment-methods-and-driver.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,15 +65,19 @@ like the element capability interfaces ([[0001-core-element-model]] §B):
```php
namespace Lunar\Core\Contracts;

interface SupportsPaymentIntents
interface ReconcilesPaymentIntents
{
public function fetchIntent(string $ref): PaymentIntentStatus; // enum: Pending, RequiresCapture,
// Captured, Voided, Failed
public function voidIntent(string $ref): void;
public function refundIntent(string $ref, int $amountMinor, string $idempotencyKey): string; // refund ref
// Null when the driver did not create the reference for the cart.
public function fetchIntent(Cart $cart, string $reference): ?PaymentIntentSnapshot;
public function voidIntent(Cart $cart, string $reference): void;
public function refundIntent(Cart $cart, string $reference, PriceValue $amount, string $idempotencyKey): PaymentRefund;
}
```

`PaymentIntentSnapshot::$status` is a `PaymentIntentStatus`: `RequiresAction`, `Processing`,
`RequiresCapture`, `Captured`, `Voided` or `Failed`. `PaymentRefund::$reference` is the
gateway's refund id.

A gateway that does not implement it **cannot be voided or reconciled**: its sessions stay in
`PaymentProcessing` and flow into the stall protocol ([[0010-cart-session-reconciliation]] §F).
The interface is also the test seam — the contract-test fake gateway implements it (§E,
Expand Down Expand Up @@ -153,9 +157,9 @@ re-verifying against the **session** total/currency before transition:

- Recompute the session cart's total and verify `intent.amount`/`currency` match before
capture/transition; on mismatch, fail and void/refund — routed through
`SupportsPaymentIntents` (§A).
`ReconcilesPaymentIntents` (§A).
- Idempotent webhook handling (atomic claim), transaction recording, and intent reconciliation —
the fetch/void/refund-by-intent calls route through `SupportsPaymentIntents` (§A).
the fetch/void/refund-by-intent calls route through `ReconcilesPaymentIntents` (§A).
- **Advisory intents.** `payment_intent_ref` is recorded at intent **creation**. A gateway
success event that resolves to a non-current intent, or to a session not in
`PaymentProcessing`, is **refunded** (`refundIntent`) — it never completes. Terminalizing an
Expand Down Expand Up @@ -201,7 +205,7 @@ session's `PaymentProcessing` state (which rejects element stores), not a cart f

- New `Lunar\Checkout\Contracts\PaymentMethod` + a payment-method registry (in `lunar/checkout`,
gateway-agnostic) and the payment host element. **No dependency on `lunar/stripe`.**
- New **core** capability contract `Lunar\Core\Contracts\SupportsPaymentIntents` + the
- New **core** capability contract `Lunar\Core\Contracts\ReconcilesPaymentIntents` + the
`PaymentIntentStatus` enum (§A) — additive, opt-in via `instanceof`; existing gateways are
unaffected until they adopt it.
- `lunar/stripe` (optional) gains a `StripeCardMethod implements PaymentMethod` + a prebuilt
Expand All @@ -219,7 +223,7 @@ session's `PaymentProcessing` state (which rejects element stores), not a cart f
- A payment-method **contract test** fixture each gateway runs to prove the seam (method resolves
a registered `AbstractPayment` driver; submit → `authorize()` → `AwaitingPayment → InProcess` +
`placed_at` + `Transaction` rows). The fixture's **fake gateway implements
`SupportsPaymentIntents`** (§A) so the intent-keyed verbs are exercised end-to-end.
`ReconcilesPaymentIntents`** (§A) so the intent-keyed verbs are exercised end-to-end.
- A gateway success event for a **non-current intent**, or for a session **not in
`PaymentProcessing`**, is refunded via `refundIntent` and never completes the session (§E).
- Terminalizing an `Open` session **voids its advisory intent first** via `voidIntent` (§E,
Expand Down
2 changes: 1 addition & 1 deletion spec/0006-worked-example.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Three packages, one contract ([[0000-overview]]):
facade, the built-in element impls, the `/checkout/{uuid}/elements/{handle}` Inertia
multiplexer. (A transport-free `checkout-core` split is an open question — [[0000-overview]].)
- **`lunar/core`** — the surfaces checkout rides: `Cart::set*`, `ShippingManifest`,
`Payments`/`AbstractPayment` (plus the `SupportsPaymentIntents` capability). No checkout code.
`Payments`/`AbstractPayment` (plus the `ReconcilesPaymentIntents` capability). No checkout code.
- **`lunar/api`** — the REST projection of the same DTO (not the spine here; see [[0003-transport-projections]] §A).

This walkthrough uses the **Inertia spine**: the self-contained checkout app renders `<LunarCheckout/>`
Expand Down
Loading
Loading