@core / stripe

1.0.0 ▾

1.0.0

已验证MIT

GitHub

共享 Stripe 客户端和单一的幂等、验签 Webhook 端点，将事件分发给各模块

代码8 个文件上下文约 545 个 tokenMCP stripe扫描通过

约 545 个 token→ 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;
    }
  });
}