@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/adapters/hono.ts읽기 전용 · 43dfe91

// Adaptador Hono: `app.route('/api/stripe/webhook', stripeWebhookRoutes())`.
import { Hono } from 'hono';
import { handleStripeWebhook, WebhookSignatureError } from '../index.ts';

export function stripeWebhookRoutes() {
  return new Hono().post('/', async (c) => {
    try {
      // Cuerpo en bruto: la firma se calcula sobre los bytes exactos.
      return c.json(await handleStripeWebhook(await c.req.text(), c.req.header('stripe-signature') ?? null));
    } catch (e) {
      if (e instanceof WebhookSignatureError) return c.json({ error: e.message }, 400);
      throw e;
    }
  });
}