@bagou/payment-stripe 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bagou
+
+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.

package/README.md

@@ -0,0 +1,158 @@
+# @bagou/payment-stripe
+
+> Part of the [bagou-packages](../../README.md) monorepo.
+
+Stripe payment abstractions built on top of the official Stripe SDK. Covers checkout sessions, webhooks, customers, subscriptions, products, discounts, and analytics — all with typed, injectable services.
+
+## Install
+
+```sh
+bun add @bagou/payment-stripe
+```
+
+Set `STRIPE_SECRET_KEY` in your environment (e.g. via `.env`):
+
+```env
+STRIPE_SECRET_KEY=sk_live_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+```
+
+## Services
+
+| Class | Responsibility |
+|-------|---------------|
+| `StripeClient` | Holds the authenticated Stripe SDK instance |
+| `StripeProvider` | High-level facade — checkout + webhooks |
+| `StripeCheckoutSession` | Create and retrieve Checkout Sessions |
+| `StripeWebhookEvent` | Verify and parse incoming webhook events |
+| `StripeCustomer` | Customer CRUD + listing |
+| `StripeCustomerPortal` | Create Billing Portal sessions |
+| `StripeDiscount` | Coupon / promo-code management |
+| `StripeProducts` | Product and price CRUD |
+| `StripeAnalytics` | Revenue and subscription summary |
+
+## Usage
+
+### Checkout session
+
+```ts
+import { StripeProvider } from "@bagou/payment-stripe";
+
+const provider = new StripeProvider();
+
+const session = await provider.createCheckoutSession({
+  lineItems: [{ price: "price_xxx", quantity: 1 }],
+  mode: "subscription",
+  successUrl: "https://example.com/success",
+  cancelUrl: "https://example.com/cancel",
+});
+
+const retrieved = await provider.retrieveSession(session.id);
+```
+
+### Webhook verification
+
+```ts
+const event = await provider.constructWebhookEvent(
+  rawBody,
+  stripeSignatureHeader,
+  process.env.STRIPE_WEBHOOK_SECRET!,
+);
+
+if (event.type === "checkout.session.completed") {
+  const data = event.data; // CheckoutSessionCompletedDataType
+}
+```
+
+### Customers
+
+```ts
+import { StripeClient, StripeCustomer } from "@bagou/payment-stripe";
+
+const customer = new StripeCustomer(new StripeClient());
+
+const created = await customer.create({ email: "user@example.com", name: "Alice" });
+const updated = await customer.update(created.id, { name: "Alice B." });
+const found   = await customer.get(created.id);
+const list    = await customer.list({ limit: 20 });
+await customer.remove(created.id);
+```
+
+### Billing Portal
+
+```ts
+import { StripeClient, StripeCustomerPortal } from "@bagou/payment-stripe";
+
+const portal = new StripeCustomerPortal(new StripeClient());
+
+const session = await portal.create({
+  customerId: "cus_xxx",
+  returnUrl: "https://example.com/account",
+});
+
+// Redirect the user to session.url
+```
+
+### Discounts (coupons)
+
+```ts
+import { StripeClient, StripeDiscount } from "@bagou/payment-stripe";
+
+const discount = new StripeDiscount(new StripeClient());
+
+const coupon = await discount.create({
+  name: "SUMMER20",
+  type: "percentage",
+  amount: 20,
+  duration: "once",
+  code: "SUMMER20",
+});
+```
+
+### Products & prices
+
+```ts
+import { StripeClient, StripeProducts } from "@bagou/payment-stripe";
+
+const products = new StripeProducts(new StripeClient());
+
+const product = await products.create({ name: "Pro Plan" });
+
+const price = await products.createPrice({
+  productId: product.id,
+  currency: "eur",
+  unitAmount: 1999,
+  type: "recurring",
+  interval: "month",
+});
+```
+
+### Analytics
+
+```ts
+import { StripeClient, StripeAnalytics } from "@bagou/payment-stripe";
+
+const analytics = new StripeAnalytics(new StripeClient());
+
+const summary = await analytics.get({
+  startDate: new Date("2025-01-01"),
+  endDate: new Date("2025-12-31"),
+  currency: "eur",
+});
+
+console.log(summary.totalRevenue, summary.activeSubscriptions);
+```
+
+## Supported Webhook Events
+
+| Event | Type constant |
+|-------|--------------|
+| `checkout.session.completed` | `EStripeEvent.CheckoutSessionCompleted` |
+| `invoice.paid` | `EStripeEvent.InvoicePaid` |
+| `customer.subscription.deleted` | `EStripeEvent.CustomerSubscriptionDeleted` |
+| `customer.subscription.updated` | `EStripeEvent.CustomerSubscriptionUpdated` |
+| `payment_intent.payment_failed` | `EStripeEvent.PaymentIntentPaymentFailed` |
+
+## License
+
+MIT © Bagou

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+import Stripe from "stripe";
+declare class StripeClient {
+	private readonly client;
+	constructor();
+	get sdk(): Stripe;
+}
+declare enum EStripeEvent {
+	CheckoutSessionCompleted = "checkout.session.completed",
+	InvoicePaid = "invoice.paid",
+	CustomerSubscriptionDeleted = "customer.subscription.deleted",
+	CustomerSubscriptionUpdated = "customer.subscription.updated",
+	PaymentIntentPaymentFailed = "payment_intent.payment_failed"
+}
+type StripeEventType = `${EStripeEvent}`;
+type LineItemType = {
+	price: string;
+	quantity?: number;
+};
+type CheckoutSessionCreateType = {
+	lineItems: LineItemType[];
+	mode: "payment" | "subscription" | "setup";
+	successUrl: string;
+	cancelUrl?: string;
+	customerId?: string;
+	customerEmail?: string;
+	metadata?: Record<string, string>;
+};
+type CheckoutSessionType = {
+	id: string;
+	url: string | null;
+	status: string | null;
+	paymentStatus: string;
+	customerId: string | null;
+	customerEmail: string | null;
+	amountTotal: number | null;
+	currency: string | null;
+	metadata: Record<string, string>;
+};
+type CheckoutSessionCompletedDataType = {
+	id: string;
+	customerId: string | null;
+	customerEmail: string | null;
+	amountTotal: number | null;
+	currency: string | null;
+	paymentStatus: string;
+	subscriptionId: string | null;
+	metadata: Record<string, string>;
+};
+type InvoicePaidDataType = {
+	id: string;
+	customerId: string | null;
+	subscriptionId: string | null;
+	amountPaid: number;
+	currency: string;
+	status: string | null;
+	hostedInvoiceUrl: string | null;
+};
+type CustomerSubscriptionDeletedDataType = {
+	id: string;
+	customerId: string | null;
+	status: string;
+	currentPeriodEnd: Date;
+	canceledAt: Date | null;
+	metadata: Record<string, string>;
+};
+type CustomerSubscriptionUpdatedDataType = {
+	id: string;
+	customerId: string | null;
+	status: string;
+	currentPeriodEnd: Date;
+	cancelAtPeriodEnd: boolean;
+	metadata: Record<string, string>;
+};
+type PaymentIntentPaymentFailedDataType = {
+	id: string;
+	customerId: string | null;
+	amount: number;
+	currency: string;
+	lastPaymentErrorMessage: string | null;
+};
+type CheckoutSessionCompletedEventType = {
+	type: EStripeEvent.CheckoutSessionCompleted;
+	id: string;
+	created: Date;
+	data: CheckoutSessionCompletedDataType;
+};
+type InvoicePaidEventType = {
+	type: EStripeEvent.InvoicePaid;
+	id: string;
+	created: Date;
+	data: InvoicePaidDataType;
+};
+type CustomerSubscriptionDeletedEventType = {
+	type: EStripeEvent.CustomerSubscriptionDeleted;
+	id: string;
+	created: Date;
+	data: CustomerSubscriptionDeletedDataType;
+};
+type CustomerSubscriptionUpdatedEventType = {
+	type: EStripeEvent.CustomerSubscriptionUpdated;
+	id: string;
+	created: Date;
+	data: CustomerSubscriptionUpdatedDataType;
+};
+type PaymentIntentPaymentFailedEventType = {
+	type: EStripeEvent.PaymentIntentPaymentFailed;
+	id: string;
+	created: Date;
+	data: PaymentIntentPaymentFailedDataType;
+};
+type WebhookEventType = CheckoutSessionCompletedEventType | InvoicePaidEventType | CustomerSubscriptionDeletedEventType | CustomerSubscriptionUpdatedEventType | PaymentIntentPaymentFailedEventType;
+interface IPaymentProvider {
+	createCheckoutSession(data: CheckoutSessionCreateType): Promise<CheckoutSessionType>;
+	retrieveSession(id: string): Promise<CheckoutSessionType>;
+	constructWebhookEvent(payload: string | Buffer, signature: string, secret: string): Promise<WebhookEventType>;
+}
+type StripeCustomerAddressType = {
+	line1?: string;
+	line2?: string;
+	city?: string;
+	state?: string;
+	postalCode?: string;
+	country?: string;
+};
+type StripeCustomerCreateType = {
+	email: string;
+	name?: string;
+	phone?: string;
+	billingAddress?: StripeCustomerAddressType;
+	metadata?: Record<string, string>;
+};
+type StripeCustomerUpdateType = {
+	email?: string;
+	name?: string;
+	phone?: string;
+	billingAddress?: StripeCustomerAddressType;
+	metadata?: Record<string, string>;
+};
+type StripeCustomerType = {
+	id: string;
+	email: string;
+	name?: string;
+	phone?: string;
+	billingAddress?: StripeCustomerAddressType;
+	metadata?: Record<string, string>;
+	createdAt?: Date;
+};
+type StripeCustomerListOptionsType = {
+	email?: string;
+	limit?: number;
+	startingAfter?: string;
+};
+type StripeCustomerListResultType = {
+	items: StripeCustomerType[];
+	hasMore: boolean;
+};
+type StripeCustomerPortalCreateType = {
+	customerId: string;
+	returnUrl: string;
+};
+type StripeCustomerPortalType = {
+	id: string;
+	url: string;
+	returnUrl: string;
+	createdAt?: Date;
+};
+declare enum EStripeDiscountType {
+	PERCENTAGE = "percentage",
+	FIXED = "fixed"
+}
+type StripeDiscountTypeType = `${EStripeDiscountType}`;
+declare enum EStripeDiscountDuration {
+	ONCE = "once",
+	REPEATING = "repeating",
+	FOREVER = "forever"
+}
+type StripeDiscountDurationType = `${EStripeDiscountDuration}`;
+type StripeDiscountCreateType = {
+	name: string;
+	type: StripeDiscountTypeType;
+	amount: number;
+	currency?: string;
+	duration: StripeDiscountDurationType;
+	durationInMonths?: number;
+	code?: string;
+	maxRedemptions?: number;
+	redeemBy?: Date;
+	metadata?: Record<string, string>;
+	appliesTo?: string[];
+};
+type StripeDiscountUpdateType = {
+	name?: string;
+	metadata?: Record<string, string>;
+};
+type StripeDiscountType = {
+	id: string;
+	name: string;
+	type: StripeDiscountTypeType;
+	amount: number;
+	currency?: string;
+	duration: StripeDiscountDurationType;
+	durationInMonths?: number;
+	code?: string;
+	maxRedemptions?: number;
+	timesRedeemed?: number;
+	redeemBy?: Date;
+	isValid?: boolean;
+	metadata?: Record<string, string>;
+	createdAt?: Date;
+};
+type StripeDiscountListOptionsType = {
+	limit?: number;
+	startingAfter?: string;
+};
+type StripeDiscountListResultType = {
+	items: StripeDiscountType[];
+	hasMore: boolean;
+};
+type StripeProductCreateType = {
+	name: string;
+	description?: string;
+	images?: string[];
+	metadata?: Record<string, string>;
+	active?: boolean;
+};
+type StripeProductUpdateType = {
+	name?: string;
+	description?: string;
+	images?: string[];
+	metadata?: Record<string, string>;
+	active?: boolean;
+};
+type StripeProductType = {
+	id: string;
+	name: string;
+	description?: string;
+	images?: string[];
+	active?: boolean;
+	metadata?: Record<string, string>;
+	createdAt?: Date;
+	updatedAt?: Date;
+};
+type StripeProductListOptionsType = {
+	limit?: number;
+	active?: boolean;
+	startingAfter?: string;
+};
+type StripeProductListResultType = {
+	items: StripeProductType[];
+	hasMore: boolean;
+};
+declare enum EStripePriceType {
+	ONE_TIME = "one_time",
+	RECURRING = "recurring"
+}
+type StripePriceTypeType = `${EStripePriceType}`;
+declare enum EStripePriceInterval {
+	DAY = "day",
+	WEEK = "week",
+	MONTH = "month",
+	YEAR = "year"
+}
+type StripePriceIntervalType = `${EStripePriceInterval}`;
+type StripePriceCreateType = {
+	productId: string;
+	currency: string;
+	unitAmount: number;
+	type?: StripePriceTypeType;
+	interval?: StripePriceIntervalType;
+	intervalCount?: number;
+	metadata?: Record<string, string>;
+};
+type StripePriceType = {
+	id: string;
+	productId: string;
+	currency: string;
+	unitAmount: number | null;
+	type: StripePriceTypeType;
+	interval?: StripePriceIntervalType;
+	intervalCount?: number;
+	active?: boolean;
+	metadata?: Record<string, string>;
+	createdAt?: Date;
+};
+type StripePriceListOptionsType = {
+	limit?: number;
+	active?: boolean;
+};
+type StripePriceListResultType = {
+	items: StripePriceType[];
+	hasMore: boolean;
+};
+type StripeAnalyticsOptionsType = {
+	startDate: Date;
+	endDate: Date;
+	limit?: number;
+	currency?: string;
+};
+type StripeAnalyticsPeriodType = {
+	date: string;
+	revenue: number;
+	currency: string;
+	transactionCount: number;
+};
+type StripeAnalyticsSummaryType = {
+	totalRevenue: number;
+	totalTransactions: number;
+	currency: string;
+	periods: StripeAnalyticsPeriodType[];
+	activeSubscriptions?: number;
+	newSubscriptions?: number;
+	canceledSubscriptions?: number;
+};
+declare class StripeAnalytics {
+	private readonly client;
+	constructor(client: StripeClient);
+	get(options: StripeAnalyticsOptionsType): Promise<StripeAnalyticsSummaryType>;
+}
+declare class StripeCheckoutSession {
+	private readonly client;
+	constructor(client: StripeClient);
+	create(data: CheckoutSessionCreateType): Promise<CheckoutSessionType>;
+	get(id: string): Promise<CheckoutSessionType>;
+	private mapSession;
+}
+declare class StripeCustomer {
+	private readonly client;
+	constructor(client: StripeClient);
+	create(data: StripeCustomerCreateType): Promise<StripeCustomerType>;
+	update(id: string, data: StripeCustomerUpdateType): Promise<StripeCustomerType>;
+	remove(id: string): Promise<void>;
+	get(id: string): Promise<StripeCustomerType>;
+	list(options?: StripeCustomerListOptionsType): Promise<StripeCustomerListResultType>;
+	private toStripeAddress;
+	private mapCustomer;
+}
+declare class StripeCustomerPortal {
+	private readonly client;
+	constructor(client: StripeClient);
+	create(data: StripeCustomerPortalCreateType): Promise<StripeCustomerPortalType>;
+}
+declare class StripeDiscount {
+	private readonly client;
+	constructor(client: StripeClient);
+	create(data: StripeDiscountCreateType): Promise<StripeDiscountType>;
+	update(id: string, data: StripeDiscountUpdateType): Promise<StripeDiscountType>;
+	remove(id: string): Promise<void>;
+	get(id: string): Promise<StripeDiscountType>;
+	list(options?: StripeDiscountListOptionsType): Promise<StripeDiscountListResultType>;
+	private mapCoupon;
+}
+declare class StripeProducts {
+	private readonly client;
+	constructor(client: StripeClient);
+	create(data: StripeProductCreateType): Promise<StripeProductType>;
+	update(id: string, data: StripeProductUpdateType): Promise<StripeProductType>;
+	remove(id: string): Promise<void>;
+	get(id: string): Promise<StripeProductType>;
+	list(options?: StripeProductListOptionsType): Promise<StripeProductListResultType>;
+	createPrice(data: StripePriceCreateType): Promise<StripePriceType>;
+	getPrice(id: string): Promise<StripePriceType>;
+	listPrices(productId: string, options?: StripePriceListOptionsType): Promise<StripePriceListResultType>;
+	private mapProduct;
+	private mapPrice;
+}
+declare class StripeWebhookEvent {
+	private readonly client;
+	constructor(client: StripeClient);
+	construct(payload: string | Buffer, signature: string, secret: string): Promise<WebhookEventType>;
+}
+declare class StripeProvider implements IPaymentProvider {
+	private readonly checkoutSession;
+	private readonly webhookEvent;
+	constructor(checkoutSession: StripeCheckoutSession, webhookEvent: StripeWebhookEvent);
+	createCheckoutSession(data: CheckoutSessionCreateType): Promise<CheckoutSessionType>;
+	retrieveSession(id: string): Promise<CheckoutSessionType>;
+	constructWebhookEvent(payload: string | Buffer, signature: string, secret: string): Promise<WebhookEventType>;
+}
+export { WebhookEventType, StripeWebhookEvent, StripeProvider, StripeProducts, StripeProductUpdateType, StripeProductType, StripeProductListResultType, StripeProductListOptionsType, StripeProductCreateType, StripePriceTypeType, StripePriceType, StripePriceListResultType, StripePriceListOptionsType, StripePriceIntervalType, StripePriceCreateType, StripeEventType, StripeDiscountUpdateType, StripeDiscountTypeType, StripeDiscountType, StripeDiscountListResultType, StripeDiscountListOptionsType, StripeDiscountDurationType, StripeDiscountCreateType, StripeDiscount, StripeCustomerUpdateType, StripeCustomerType, StripeCustomerPortalType, StripeCustomerPortalCreateType, StripeCustomerPortal, StripeCustomerListResultType, StripeCustomerListOptionsType, StripeCustomerCreateType, StripeCustomerAddressType, StripeCustomer, StripeClient, StripeCheckoutSession, StripeAnalyticsSummaryType, StripeAnalyticsPeriodType, StripeAnalyticsOptionsType, StripeAnalytics, PaymentIntentPaymentFailedEventType, PaymentIntentPaymentFailedDataType, LineItemType, InvoicePaidEventType, InvoicePaidDataType, IPaymentProvider, EStripePriceType, EStripePriceInterval, EStripeEvent, EStripeDiscountType, EStripeDiscountDuration, CustomerSubscriptionUpdatedEventType, CustomerSubscriptionUpdatedDataType, CustomerSubscriptionDeletedEventType, CustomerSubscriptionDeletedDataType, CheckoutSessionType, CheckoutSessionCreateType, CheckoutSessionCompletedEventType, CheckoutSessionCompletedDataType };