@codesled/stripe-payments/README.md

Simple Stripe checkout integration module from CodeSled

# @codesled/stripe-payments

Simple, composable Stripe checkout integration for Node.js applications. Create Stripe Checkout sessions and verify webhooks with minimal setup — no boilerplate, no complexity.

Framework-agnostic and dev-first. Designed to make payments frictionless to implement.

> 🚀 Part of the CodeSled developer toolkit — reusable modules that help you build apps faster.

---


## Features

- Create Stripe Checkout sessions with one function
- Supports both **one-time** and **subscription** payments
- Minimal setup with secure defaults
- Verify Stripe webhook signatures
- Compatible with Express, Next.js, or any Node backend
- Plug-and-play — no need to read Stripe docs
- Now supports manual Stripe key initialization with `initStripe()`

---


## Installation

```bash
npm install @codesled/stripe-payments
```

> You must have a Stripe account and access to secret keys.

---


## Environment Setup

Create a `.env` file (or set env variables) with the following:

```
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
```

These values are found in your [Stripe Dashboard](https://dashboard.stripe.com/test/apikeys).

---


## Initialization

You **must call `initStripe()` once** before using `createCheckoutSession()` or `verifyWebhookSignature()`.

### Option 1 — Using `.env` (recommended):

```js
require("dotenv").config();
const { initStripe } = require("@codesled/stripe-payments");

initStripe(); // uses STRIPE_SECRET_KEY from .env
```

### Option 2 — Manual Stripe key:

```js
const { initStripe } = require("@codesled/stripe-payments");

initStripe("sk_test_yourSecretKeyHere");
```

---


## Usage Example

### Creating a Checkout Session

```js
const {
  initStripe,
  createCheckoutSession,
} = require('@codesled/stripe-payments');

initStripe(); // or pass the key manually

const sessionUrl = await createCheckoutSession({
  priceId: 'price_123',
  successUrl: 'https://yourapp.com/success',
  cancelUrl: 'https://yourapp.com/cancel',
  customerEmail: 'user@example.com',
  mode: 'payment' // "payment" for one-time or "subscription" for recurring
});

console.log('Redirect to:', sessionUrl);
```

---


### Verifying Webhook Events

Use in a raw body parser route (e.g. in Express or Next.js API route):

```js
const {
  initStripe,
  verifyWebhookSignature,
} = require('@codesled/stripe-payments');

initStripe(); // or initStripe("sk_test_...")

const event = verifyWebhookSignature(req.rawBody, req.headers['stripe-signature']);

// Handle event type
if (event.type === 'checkout.session.completed') {
  const session = event.data.object;
  console.log('Checkout complete:', session.id);
}
```

---


## Functions

| Function                   | Purpose                                        |
|----------------------------|------------------------------------------------|
| `initStripe()`             | Initializes Stripe with your secret key       |
| `createCheckoutSession()`  | Generate a hosted Stripe Checkout session URL |
| `verifyWebhookSignature()` | Validate incoming webhook using Stripe secret |

---


## Notes

- Supports both **subscription mode** and **one-time mode** via the `mode` option.
- Requires raw body middleware for webhook validation (e.g., `express.raw({ type: 'application/json' })`).
- `initStripe()` must be called before any other function.

---


## Local Testing

Use Stripe CLI or Dashboard to trigger test webhooks:

```bash
stripe listen --forward-to localhost:3000/webhook
```

---


## Why Use This Package?

Stripe is powerful, but overkill for simple needs. This package abstracts away Stripe’s verbose API and lets you:

- 🚫 Avoid boilerplate
- 🧐 Skip reading docs
- 🧹 Reuse across all CodeSled apps

Focus on shipping — we handle the payment logic.

---


## License

MIT — Free to use, share, and build on.

---


## About CodeSled

**CodeSled** is a modular developer toolkit — reusable code blocks for core app functionality (auth, payments, CMS, and more). Build faster. Ship smarter.

> Follow [@codesled](https://github.com/code-sled) for updates.