@core / checkout

1.0.1 ▾

1.0.1

인증됨MIT

GitHub

일회성 구매용 Stripe Checkout: 서버 가격, 웹훅에서만 주문 생성, 품절 시 자동 환불

코드파일 8개컨텍스트약 707토큰MCP stripe검사 통과

약 707토큰→ src/lib/checkout/AGENTS.md→ .cursor/rules/genpm-core-checkout.mdc

이것이 AI가 src/lib/checkout에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

@core/checkout — rules for AI agents

Purpose

Pays a @core/cart with Stripe Checkout (hosted page: no card data on your server). startCheckout recomputes totals, blocks carts with issues or without shipping, sends server prices, a one-off coupon for the computed discounts and the chosen shipping rate, and stores a snapshot. The order (@core/orders) is created ONLY in the Stripe webhook, idempotently, from that snapshot after checking the charged amount; if the order can never be created (stock ran out, a variant was withdrawn, invalid address…), the payment is refunded automatically, the customer and the team are told and the webhook still answers 2xx (transient errors are rethrown so Stripe retries). Open sessions reserve the discount codes they carry (registerPendingCodeUses of @core/cart); if a concurrent checkout took the last use, the new session is expired and startCheckout throws issues. Also registers Stripe as the refund provider for the admin.

Map

index.ts — public API: startCheckout, getCheckoutStatus, finalizeSession, stripePaymentProvider, beginCheckoutEvent, purchaseEvent.
checkout.ts — logic and webhook handlers (registered on import). schema.ts — checkout_sessions.
adapters/hono.ts — checkoutRoutes({ currentUserId }). adapters/next.ts — checkoutRoute, checkoutStatusRoute.

Integration

Install and wire @core/stripe (one webhook endpoint) with events checkout.session.completed, checkout.session.async_payment_succeeded and checkout.session.expired. Env: SITE_URL, EMAIL_FROM, optional CHECKOUT_ALERT_TO (team alerts) and STRIPE_TAX=1 (Stripe Tax; configure it in Stripe first).
Import this module and @core/shipping at startup. Migrations as in src/lib/db/AGENTS.md; the @core/jobs cron must run.
Cart page → ask country and shipping rate (setCartMeta), then POST /api/checkout {email} → redirect to url.
Success page /checkout/success?session_id=…: poll GET /api/checkout/status until paid (show the order number), refunded (sold out or order could not be created) or keep "processing" — never trust the URL alone.
Verify locally: stripe listen --forward-to localhost:3000/api/stripe/webhook, pay with card 4242 4242 4242 4242, an order appears.

Conventions

Amounts always come from computeTotals; the snapshot is what the customer saw and paid.
Show delivery estimate, total with shipping and taxes, and legal links before redirecting to Stripe.
Use purchaseEvent(order) (same eventId in browser and server) for @core/pixels.

Don't

Don't create or mark orders paid from the success redirect or from client calls.
Don't send prices, discounts or shipping amounts from the browser to Stripe.
Don't log card data, full webhook payloads or Stripe keys.

# @core/checkout — rules for AI agents

## Purpose
Pays a @core/cart with Stripe Checkout (hosted page: no card data on your server). `startCheckout` recomputes totals,
blocks carts with issues or without shipping, sends server prices, a one-off coupon for the computed discounts and
the chosen shipping rate, and stores a snapshot. The order (@core/orders) is created ONLY in the Stripe webhook,
idempotently, from that snapshot after checking the charged amount; if the order can never be created (stock ran
out, a variant was withdrawn, invalid address…), the payment is refunded automatically, the customer and the team
are told and the webhook still answers 2xx (transient errors are rethrown so Stripe retries). Open sessions reserve
the discount codes they carry (`registerPendingCodeUses` of @core/cart); if a concurrent checkout took the last use,
the new session is expired and `startCheckout` throws `issues`. Also registers Stripe as the refund provider for the admin.

## Map
- `index.ts` — public API: `startCheckout`, `getCheckoutStatus`, `finalizeSession`, `stripePaymentProvider`, `beginCheckoutEvent`, `purchaseEvent`.
- `checkout.ts` — logic and webhook handlers (registered on import). `schema.ts` — `checkout_sessions`.
- `adapters/hono.ts` — `checkoutRoutes({ currentUserId })`. `adapters/next.ts` — `checkoutRoute`, `checkoutStatusRoute`.

## Integration
1. Install and wire @core/stripe (one webhook endpoint) with events `checkout.session.completed`,
   `checkout.session.async_payment_succeeded` and `checkout.session.expired`. Env: `SITE_URL`, `EMAIL_FROM`,
   optional `CHECKOUT_ALERT_TO` (team alerts) and `STRIPE_TAX=1` (Stripe Tax; configure it in Stripe first).
2. Import this module and @core/shipping at startup. Migrations as in `src/lib/db/AGENTS.md`; the @core/jobs cron must run.
3. Cart page → ask country and shipping rate (`setCartMeta`), then `POST /api/checkout {email}` → redirect to `url`.
4. Success page `/checkout/success?session_id=…`: poll `GET /api/checkout/status` until `paid` (show the order number),
   `refunded` (sold out or order could not be created) or keep "processing" — never trust the URL alone.
5. Verify locally: `stripe listen --forward-to localhost:3000/api/stripe/webhook`, pay with card 4242 4242 4242 4242, an order appears.

## Conventions
- Amounts always come from `computeTotals`; the snapshot is what the customer saw and paid.
- Show delivery estimate, total with shipping and taxes, and legal links before redirecting to Stripe.
- Use `purchaseEvent(order)` (same `eventId` in browser and server) for @core/pixels.

## Don't
- Don't create or mark orders paid from the success redirect or from client calls.
- Don't send prices, discounts or shipping amounts from the browser to Stripe.
- Don't log card data, full webhook payloads or Stripe keys.

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/lib/checkout/LICENSE읽기 전용 · 6590fd9

MIT License

Copyright (c) 2026 GenPM

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

버전	커밋	게시일	검사
1.0.1	6590fd9	6시간 전	검사 통과

$genpm add @core/checkout

주입 위치: src/lib/checkout
커밋
태그: v1.0.1
필요: @core/cart ^1.1.0 @core/catalog ^1.0.0 @core/email ^1.0.1 @core/jobs ^1.0.0 @core/money ^1.0.0 @core/orders ^1.0.0 @core/shipping ^1.0.0 @core/stripe ^1.0.0
npm: stripe ^23.0.0zod ^4.0.0
Env: SITE_URL STRIPE_TAX CHECKOUT_ALERT_TO
품질: 100/100
사용처: 1
설치 수: 0 / 30일
게시일: 6시간 전 · genpm-system

README 배지

[![genpm](https://api.genpm.net/v1/badge/@core/checkout.svg)](https://genpm.net/p/@core/checkout)