@core / stripe

1.0.0 ▾

1.0.0

인증됨MIT

GitHub

공유 Stripe 클라이언트와 서명 검증·멱등 처리되는 단일 웹훅, 각 모듈로 이벤트 전달

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

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

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

@core/stripe — rules for AI agents

Purpose

The single Stripe integration point of the app: a lazily created client (getStripe) and ONE webhook endpoint that verifies the signature, records each event in stripe_events (idempotency) and dispatches it, inside one database transaction, to the handlers that modules register with onStripeEvent (@core/billing 2.x, @core/checkout…). If a handler throws, everything rolls back and Stripe retries. No business logic here.

Map

index.ts — public API: getStripe, setStripe, onStripeEvent, handleStripeWebhook, stripeEvents.
webhooks.ts — verification, idempotency and dispatch. client.ts — client. schema.ts — stripe_events.
adapters/hono.ts — stripeWebhookRoutes(). adapters/next.ts — stripeWebhookRoute.

Integration

Env: STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET (whsec_…). Migrations as in src/lib/db/AGENTS.md.
Mount the endpoint: Hono app.route('/api/stripe/webhook', stripeWebhookRoutes()); Next.js app/api/stripe/webhook/route.ts → export { stripeWebhookRoute as POST } from '@/lib/stripe/adapters/next'.
In Stripe, create one webhook endpoint <origin>/api/stripe/webhook with the events the installed modules list in their AGENTS.md. Locally: stripe listen --forward-to localhost:3000/api/stripe/webhook.
Import the modules that register handlers at startup (their index.ts registers them on import).
Verify: stripe trigger checkout.session.completed returns 200 and a row appears in stripe_events.
Optional MCP: with consent, the agent can use Stripe's MCP server to look up products and prices in test mode.

Conventions

Handlers write only through the tx they receive and must be idempotent.
Read the current object from the API when order matters (events can arrive out of order).
@core/billing 1.x also defines stripe_events; upgrade it to 2.x before installing this module.

Don't

Don't create more webhook endpoints or call constructEvent elsewhere.
Don't parse the webhook body as JSON before verification; the signature covers the raw bytes.
Don't log full event payloads, card data or keys.

# @core/stripe — rules for AI agents

## Purpose
The single Stripe integration point of the app: a lazily created client (`getStripe`) and ONE webhook endpoint that
verifies the signature, records each event in `stripe_events` (idempotency) and dispatches it, inside one database
transaction, to the handlers that modules register with `onStripeEvent` (@core/billing 2.x, @core/checkout…).
If a handler throws, everything rolls back and Stripe retries. No business logic here.

## Map
- `index.ts` — public API: `getStripe`, `setStripe`, `onStripeEvent`, `handleStripeWebhook`, `stripeEvents`.
- `webhooks.ts` — verification, idempotency and dispatch. `client.ts` — client. `schema.ts` — `stripe_events`.
- `adapters/hono.ts` — `stripeWebhookRoutes()`. `adapters/next.ts` — `stripeWebhookRoute`.

## Integration
1. Env: `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` (`whsec_…`). Migrations as in `src/lib/db/AGENTS.md`.
2. Mount the endpoint: Hono `app.route('/api/stripe/webhook', stripeWebhookRoutes())`; Next.js
   `app/api/stripe/webhook/route.ts` → `export { stripeWebhookRoute as POST } from '@/lib/stripe/adapters/next'`.
3. In Stripe, create one webhook endpoint `<origin>/api/stripe/webhook` with the events the installed modules list in
   their AGENTS.md. Locally: `stripe listen --forward-to localhost:3000/api/stripe/webhook`.
4. Import the modules that register handlers at startup (their `index.ts` registers them on import).
5. Verify: `stripe trigger checkout.session.completed` returns 200 and a row appears in `stripe_events`.
6. Optional MCP: with consent, the agent can use Stripe's MCP server to look up products and prices in test mode.

## Conventions
- Handlers write only through the `tx` they receive and must be idempotent.
- Read the current object from the API when order matters (events can arrive out of order).
- @core/billing 1.x also defines `stripe_events`; upgrade it to 2.x before installing this module.

## Don't
- Don't create more webhook endpoints or call `constructEvent` elsewhere.
- Don't parse the webhook body as JSON before verification; the signature covers the raw bytes.
- Don't log full event payloads, card data or keys.

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

src/lib/stripe/LICENSE읽기 전용 · 43dfe91

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.