@core / stripe

1.0.0 ▾

1.0.0

verifiziertMIT

GitHub

Gemeinsamer Stripe-Client und ein idempotenter, signaturgeprüfter Webhook, der Events an alle Module verteilt

Code8 DateienKontext~545 TokensMCP stripePrüfung bestanden

~545 Tokens→ src/lib/stripe/AGENTS.md→ .cursor/rules/genpm-core-stripe.mdc

Genau das liest deine KI, wenn sie in src/lib/stripe arbeitet. Sonst wird ihrem Kontext nichts hinzugefügt.

@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.

Der genaue Baum, der nach .genpmignore eingebunden wird. Gepinnt an

src/lib/stripe/LICENSEschreibgeschützt · 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.