@fragno-dev/stripe 2.0.0 → 2.0.2

package/dist/node/index.js

@@ -1,8 +1,8 @@
 import { createClientBuilder } from "@fragno-dev/core/client";
-import Stripe from "stripe";
-import { column, idColumn, schema } from "@fragno-dev/db/schema";
 import { defineFragment, defineRoutes, instantiate } from "@fragno-dev/core";
+import Stripe from "stripe";
 import { withDatabase } from "@fragno-dev/db";
+import { column, idColumn, schema } from "@fragno-dev/db/schema";
 import { z } from "zod";
 import { FragnoApiError } from "@fragno-dev/core/api";
 
@@ -59,81 +59,89 @@ const defaultLogger = {
 	log: (...data) => console.log(LOG_PREFIX, ...data)
 };
 const asExternalSubscription = (subscription) => ({
-	...subscription,
 	id: subscription.id.externalId,
-	status: subscription.status
+	referenceId: subscription.referenceId,
+	stripePriceId: subscription.stripePriceId,
+	stripeCustomerId: subscription.stripeCustomerId,
+	stripeSubscriptionId: subscription.stripeSubscriptionId,
+	status: subscription.status,
+	periodStart: subscription.periodStart,
+	periodEnd: subscription.periodEnd,
+	trialStart: subscription.trialStart,
+	trialEnd: subscription.trialEnd,
+	cancelAtPeriodEnd: subscription.cancelAtPeriodEnd,
+	cancelAt: subscription.cancelAt,
+	seats: subscription.seats,
+	createdAt: subscription.createdAt,
+	updatedAt: subscription.updatedAt
 });
-function createStripeServices(deps, db) {
-	const services = {
+function createStripeServices(deps, defineService) {
+	return defineService({
 		getStripeClient() {
 			return deps.stripe;
 		},
-		createSubscription: async (data) => {
-			return (await db.create("subscription", data)).externalId;
+		createSubscription(data) {
+			return this.serviceTx(stripeSchema).mutate(({ uow }) => {
+				const created = uow.create("subscription", data);
+				return created.externalId;
+			}).build();
 		},
-		updateSubscription: async (id, data) => {
-			await db.update("subscription", id, (b) => b.set({
+		updateSubscription(id, data) {
+			return this.serviceTx(stripeSchema).mutate(({ uow }) => uow.update("subscription", id, (b) => b.set({
 				...data,
 				updatedAt: new Date()
-			}));
+			}))).build();
 		},
-		getSubscriptionByStripeId: async (stripeSubscriptionId) => {
-			const result = await db.findFirst("subscription", (b) => b.whereIndex("idx_stripe_subscription_id", (eb) => eb("stripeSubscriptionId", "=", stripeSubscriptionId)));
-			if (!result) return null;
-			return asExternalSubscription(result);
+		getSubscriptionByStripeId(stripeSubscriptionId) {
+			return this.serviceTx(stripeSchema).retrieve((uow) => uow.findFirst("subscription", (b) => b.whereIndex("idx_stripe_subscription_id", (eb) => eb("stripeSubscriptionId", "=", stripeSubscriptionId)))).transformRetrieve(([result]) => result ? asExternalSubscription(result) : null).build();
 		},
-		getSubscriptionsByStripeCustomerId: async (stripeCustomerId) => {
-			return (await db.find("subscription", (b) => b.whereIndex("idx_stripe_customer_id", (eb) => eb("stripeCustomerId", "=", stripeCustomerId)))).map(asExternalSubscription);
+		getSubscriptionsByStripeCustomerId(stripeCustomerId) {
+			return this.serviceTx(stripeSchema).retrieve((uow) => uow.find("subscription", (b) => b.whereIndex("idx_stripe_customer_id", (eb) => eb("stripeCustomerId", "=", stripeCustomerId)))).transformRetrieve(([result]) => result.map(asExternalSubscription)).build();
 		},
-		getSubscriptionById: async (id) => {
-			const result = await db.findFirst("subscription", (b) => b.whereIndex("primary", (eb) => eb("id", "=", id)));
-			if (!result) return null;
-			return asExternalSubscription(result);
+		getSubscriptionById(id) {
+			return this.serviceTx(stripeSchema).retrieve((uow) => uow.findFirst("subscription", (b) => b.whereIndex("primary", (eb) => eb("id", "=", id)))).transformRetrieve(([result]) => result ? asExternalSubscription(result) : null).build();
 		},
-		getSubscriptionsByReferenceId: async (referenceId) => {
-			const result = await db.find("subscription", (b) => b.whereIndex("idx_reference_id", (eb) => eb("referenceId", "=", referenceId)));
-			if (result.length == 0) return [];
-			return result.map(asExternalSubscription);
+		getSubscriptionsByReferenceId(referenceId) {
+			return this.serviceTx(stripeSchema).retrieve((uow) => uow.find("subscription", (b) => b.whereIndex("idx_reference_id", (eb) => eb("referenceId", "=", referenceId)))).transformRetrieve(([result]) => result.map(asExternalSubscription)).build();
 		},
-		deleteSubscription: async (id) => {
-			await db.delete("subscription", id);
+		deleteSubscription(id) {
+			return this.serviceTx(stripeSchema).mutate(({ uow }) => uow.delete("subscription", id)).build();
 		},
-		deleteSubscriptionsByReferenceId: async (referenceId) => {
-			const uow = db.createUnitOfWork().find("subscription", (b) => b.whereIndex("idx_reference_id", (eb) => eb("referenceId", "=", referenceId)));
-			const [subscriptions] = await uow.executeRetrieve();
-			subscriptions.forEach((sub) => sub && uow.delete("subscription", sub.id));
-			return await uow.executeMutations();
+		deleteSubscriptionsByReferenceId(referenceId) {
+			return this.serviceTx(stripeSchema).retrieve((uow) => uow.find("subscription", (b) => b.whereIndex("idx_reference_id", (eb) => eb("referenceId", "=", referenceId)))).mutate(({ uow, retrieveResult: [subscriptions] }) => {
+				subscriptions.forEach((sub) => {
+					uow.delete("subscription", sub.id);
+				});
+				return { success: true };
+			}).build();
 		},
-		getAllSubscriptions: async () => {
-			return (await db.find("subscription", (b) => b.whereIndex("primary"))).map(asExternalSubscription);
+		getAllSubscriptions() {
+			return this.serviceTx(stripeSchema).retrieve((uow) => uow.find("subscription", (b) => b.whereIndex("primary"))).transformRetrieve(([result]) => result.map(asExternalSubscription)).build();
 		},
-		syncStripeSubscriptions: async (referenceId, stripeCustomerId) => {
-			const stripeSubscriptions = await deps.stripe.subscriptions.list({
-				customer: stripeCustomerId,
-				status: "all"
-			});
-			if (stripeSubscriptions.data.length === 0) {
-				await services.deleteSubscriptionsByReferenceId(referenceId);
-				return { success: true };
-			}
-			const uow = db.createUnitOfWork().find("subscription", (b) => b.whereIndex("idx_reference_id", (eb) => eb("referenceId", "=", referenceId)));
-			const [existingSubscriptions] = await uow.executeRetrieve();
-			for (const stripeSubscription of stripeSubscriptions.data) {
-				const existingSubscription = existingSubscriptions.find((sub) => sub.stripeSubscriptionId === stripeSubscription.id);
-				if (existingSubscription) uow.update("subscription", existingSubscription.id, (b) => b.set({
-					...stripeSubscriptionToInternalSubscription(stripeSubscription),
-					updatedAt: new Date()
-				}).check());
-				else uow.create("subscription", {
-					...stripeSubscriptionToInternalSubscription(stripeSubscription),
-					referenceId: referenceId ?? null,
-					updatedAt: new Date()
+		syncStripeSubscriptions(referenceId, _stripeCustomerId, stripeSubscriptions) {
+			if (stripeSubscriptions.length === 0) return this.serviceTx(stripeSchema).retrieve((uow) => uow.find("subscription", (b) => b.whereIndex("idx_reference_id", (eb) => eb("referenceId", "=", referenceId)))).mutate(({ uow, retrieveResult: [subscriptions] }) => {
+				subscriptions.forEach((sub) => {
+					uow.delete("subscription", sub.id);
 				});
-			}
-			return uow.executeMutations();
+				return { success: true };
+			}).build();
+			return this.serviceTx(stripeSchema).retrieve((uow) => uow.find("subscription", (b) => b.whereIndex("idx_reference_id", (eb) => eb("referenceId", "=", referenceId)))).mutate(({ uow, retrieveResult: [existingSubscriptions] }) => {
+				for (const stripeSubscription of stripeSubscriptions) {
+					const existingSubscription = existingSubscriptions.find((sub) => sub.stripeSubscriptionId === stripeSubscription.id);
+					if (existingSubscription) uow.update("subscription", existingSubscription.id, (b) => b.set({
+						...stripeSubscriptionToInternalSubscription(stripeSubscription),
+						updatedAt: new Date()
+					}).check());
+					else uow.create("subscription", {
+						...stripeSubscriptionToInternalSubscription(stripeSubscription),
+						referenceId: referenceId ?? null,
+						updatedAt: new Date()
+					});
+				}
+				return { success: true };
+			}).build();
 		}
-	};
-	return services;
+	});
 }
 const stripeFragmentDefinition = defineFragment("stripe").extend(withDatabase(stripeSchema)).withDependencies(({ config }) => {
 	const stripeClient = new Stripe(config.stripeSecretKey, config.stripeClientOptions ?? {});
@@ -141,233 +149,7 @@ const stripeFragmentDefinition = defineFragment("stripe").extend(withDatabase(st
 		stripe: stripeClient,
 		log: config.logger ? config.logger : defaultLogger
 	};
-}).providesBaseService(({ deps }) => {
-	return { ...createStripeServices(deps, deps.db) };
-}).build();
-
-//#endregion
-//#region src/webhook/handlers.ts
-/**
-* Event Handler for checkout.session.completed
-*
-* This handler is ONLY for subscription checkout sessions.
-* Occurs when a Checkout Session has been successfully completed.
-*/
-async function checkoutSessionCompletedHandler({ event, services, deps }) {
-	const checkoutSession = event.data.object;
-	if (checkoutSession.mode !== "subscription") {
-		deps.log.info(`Not handling checkout session with mode ${checkoutSession.mode}: ${event.id}`);
-		return;
-	}
-	const subscriptionId = checkoutSession.subscription;
-	if (typeof subscriptionId !== "string") {
-		deps.log.error("No subscription ID in checkout session");
-		return;
-	}
-	const stripeSubscription = await deps.stripe.subscriptions.retrieve(subscriptionId);
-	const customerId = getId(stripeSubscription.customer);
-	const firstItem = stripeSubscription.items.data[0];
-	if (!firstItem) {
-		deps.log.error("No subscription items found");
-		return;
-	}
-	const referenceId = checkoutSession.metadata?.["referenceId"] || checkoutSession.client_reference_id;
-	const existingSubscriptionId = checkoutSession.metadata?.["subscriptionId"];
-	const subscriptionData = {
-		...stripeSubscriptionToInternalSubscription(stripeSubscription),
-		referenceId: referenceId ?? null
-	};
-	if (existingSubscriptionId) {
-		await services.updateSubscription(existingSubscriptionId, subscriptionData);
-		deps.log.info(`Updated subscription ${existingSubscriptionId} for customer ${customerId}`);
-		return;
-	}
-	const existing = await services.getSubscriptionByStripeId(stripeSubscription.id);
-	if (existing) {
-		deps.log.info(`Subscription already exists for Stripe ID ${stripeSubscription.id}`);
-		return;
-	}
-	const createdSubscriptionId = await services.createSubscription(subscriptionData);
-	deps.log.info(`Created subscription ${createdSubscriptionId} for customer ${customerId} (Stripe ID: ${stripeSubscription.id})`);
-}
-/**
-* Event Handler for customer.subscription.paused
-*
-* Occurs whenever a customer’s subscription is paused. Only applies when
-* subscriptions enter status=paused, not when payment collection is paused.
-*
-* PAUSED status: The subscription has ended its trial period without a default
-* payment method and the trial_settings.end_behavior.missing_payment_method is set
-* to pause. Invoices are no longer created for the subscription. After attaching a
-* default payment method to the customer, you can resume the subscription.
-*/
-async function customerSubscriptionPausedHandler(args) {
-	return customerSubscriptionUpdatedHandler(args);
-}
-/**
-* Event Handler for customer.subscription.pending_update_applied
-*
-* Occurs whenever a customer’s subscription’s pending update is applied,
-* and the subscription is updated.
-*/
-async function customerSubscriptionPendingUpdateAppliedHandler(args) {
-	return customerSubscriptionUpdatedHandler(args);
-}
-/**
-* Event Handler for customer.subscription.pending_update_expired
-*
-* Occurs whenever a customer’s subscription’s pending update expires
-* before the related invoice is paid.
-*/
-async function customerSubscriptionPendingUpdateExpiredHandler(args) {
-	return customerSubscriptionUpdatedHandler(args);
-}
-/**
-* Event Handler for customer.subscription.resumed
-*
-* Occurs whenever a customer’s subscription is no longer paused.
-* Only applies when a status=paused subscription is resumed, not when payment
-* collection is resumed.
-*/
-async function customerSubscriptionResumedHandler(args) {
-	return customerSubscriptionUpdatedHandler(args);
-}
-/**
-* Event Handler for customer.subscription.trial_will_end
-*
-* Occurs three days before a subscription's trial period is scheduled to end,
-* or when a trial is ended immediately (using trial_end=now). This event allows
-* you to send reminders or take action before the trial expires.
-*/
-async function customerSubscriptionTrialWillEndHandler(args) {
-	return customerSubscriptionUpdatedHandler(args);
-}
-/**
-* Event Handler for customer.subscription.updated
-*
-* Occurs whenever a subscription changes (e.g., switching from one plan to another,
-* or changing the status from trial to active).
-*/
-async function customerSubscriptionUpdatedHandler({ event, services, deps }) {
-	deps.log.info(`Processing ${event.type}: ${event.id}`);
-	const stripeSubscription = event.data.object;
-	const firstItem = stripeSubscription.items?.data?.[0];
-	if (!firstItem) throw new FragnoApiError({
-		message: "Subscription contains no items",
-		code: "EMPTY_SUBSCRIPTION"
-	}, 400);
-	const customerId = getId(stripeSubscription.customer);
-	let subscription = await services.getSubscriptionByStripeId(stripeSubscription.id);
-	if (!subscription) {
-		const customerSubs = await services.getSubscriptionsByStripeCustomerId(customerId);
-		if (customerSubs.length > 1) {
-			subscription = customerSubs.find((sub) => sub.status === "active" || sub.status === "trialing") ?? null;
-			if (!subscription) {
-				deps.log.warn(`Multiple subscriptions found for customer ${customerId} but none active or trialing`);
-				return;
-			}
-		} else subscription = customerSubs[0] ?? null;
-	}
-	if (!subscription) {
-		deps.log.warn(`No subscription found for Stripe ID ${stripeSubscription.id}, creating new record`);
-		const createdSubscriptionId = await services.createSubscription({
-			...stripeSubscriptionToInternalSubscription(stripeSubscription),
-			referenceId: stripeSubscription.metadata?.["referenceId"] ?? null
-		});
-		deps.log.info(`Created subscription ${createdSubscriptionId} for customer ${customerId} (Stripe ID: ${stripeSubscription.id})`);
-		return;
-	}
-	await services.updateSubscription(subscription.id, stripeSubscriptionToInternalSubscription(stripeSubscription));
-	deps.log.info(`Updated subscription ${subscription.id} (Stripe ID: ${stripeSubscription.id})`);
-}
-/**
-* Event Handler for customer.subscription.deleted
-*
-* Occurs whenever a customer's subscription ends.
-*/
-async function customerSubscriptionDeletedHandler({ event, services, deps }) {
-	deps.log.info(`Processing customer.subscription.deleted: ${event.id}`);
-	const stripeSubscription = event.data.object;
-	const subscription = await services.getSubscriptionByStripeId(stripeSubscription.id);
-	if (!subscription) {
-		deps.log.warn(`No subscription found for Stripe ID ${stripeSubscription.id}`);
-		return;
-	}
-	await services.updateSubscription(subscription.id, { status: "canceled" });
-	deps.log.info(`Marked subscription ${subscription.id} as canceled (Stripe ID: ${stripeSubscription.id})`);
-}
-const eventToHandler = {
-	"checkout.session.completed": checkoutSessionCompletedHandler,
-	"customer.subscription.deleted": customerSubscriptionDeletedHandler,
-	"customer.subscription.created": customerSubscriptionUpdatedHandler,
-	"customer.subscription.updated": customerSubscriptionUpdatedHandler,
-	"customer.subscription.paused": customerSubscriptionPausedHandler,
-	"customer.subscription.pending_update_applied": customerSubscriptionPendingUpdateAppliedHandler,
-	"customer.subscription.pending_update_expired": customerSubscriptionPendingUpdateExpiredHandler,
-	"customer.subscription.resumed": customerSubscriptionResumedHandler,
-	"customer.subscription.trial_will_end": customerSubscriptionTrialWillEndHandler
-};
-
-//#endregion
-//#region src/routes/webhooks.ts
-const webhookRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({ config, deps, services, defineRoute }) => {
-	return [defineRoute({
-		method: "POST",
-		path: "/webhook",
-		outputSchema: z.object({ success: z.boolean() }),
-		errorCodes: [
-			"MISSING_SIGNATURE",
-			"WEBHOOK_SIGNATURE_INVALID",
-			"WEBHOOK_ERROR"
-		],
-		handler: async ({ headers, rawBody }, { json, error }) => {
-			const signature = headers.get("stripe-signature");
-			if (!signature) return error({
-				message: "Missing stripe-signature header",
-				code: "MISSING_SIGNATURE"
-			}, 400);
-			if (!rawBody) return error({
-				message: "Missing request body for webhook verification",
-				code: "WEBHOOK_ERROR"
-			}, 400);
-			let event;
-			try {
-				if (typeof deps.stripe.webhooks.constructEventAsync === "function") event = await deps.stripe.webhooks.constructEventAsync(rawBody, signature, config.webhookSecret);
-				else event = deps.stripe.webhooks.constructEvent(rawBody, signature, config.webhookSecret);
-			} catch (err) {
-				if (err instanceof Stripe.errors.StripeSignatureVerificationError) return error({
-					message: `Webhook signature verification failed`,
-					code: "WEBHOOK_SIGNATURE_INVALID"
-				}, 400);
-				throw err;
-			}
-			if (!event) return error({
-				message: "Failed to construct event",
-				code: "WEBHOOK_ERROR"
-			}, 400);
-			if (config.onEvent) {
-				deps.log.info("Running user callback event");
-				await config.onEvent({
-					event,
-					stripeClient: deps.stripe
-				});
-			}
-			const eventHandler = eventToHandler[event.type];
-			if (!eventHandler) {
-				deps.log.info(`Webhook event ${event.type}: ${event.id} ignored`);
-				return json({ success: true });
-			}
-			deps.log.info(`Executing event handler for ${event.type}: ${event.id}`);
-			await eventHandler({
-				event,
-				services,
-				deps,
-				config
-			});
-			return json({ success: true });
-		}
-	})];
-});
+}).providesBaseService(({ deps, defineService }) => createStripeServices(deps, defineService)).build();
 
 //#endregion
 //#region src/models/customers.ts
@@ -485,57 +267,191 @@ const customersRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({
 });
 
 //#endregion
-//#region src/models/subscriptions.ts
-const SubscriptionReponseSchema = z.object({
+//#region src/models/prices.ts
+const PriceResponseSchema = z.object({
 	id: z.string(),
-	stripeSubscriptionId: z.string(),
-	stripeCustomerId: z.string(),
-	stripePriceId: z.string(),
-	referenceId: z.string().nullable(),
-	status: z.enum([
-		"active",
-		"canceled",
-		"incomplete",
-		"incomplete_expired",
-		"past_due",
-		"paused",
-		"trialing",
-		"unpaid"
-	]),
-	periodStart: z.date().nullable(),
-	periodEnd: z.date().nullable(),
-	trialStart: z.date().nullable(),
-	trialEnd: z.date().nullable(),
-	cancelAtPeriodEnd: z.boolean().nullable(),
-	cancelAt: z.date().nullable(),
-	seats: z.number().nullable(),
-	createdAt: z.date(),
-	updatedAt: z.date()
-});
-const SubscriptionUpgradeRequestSchema = z.object({
-	priceId: z.string().describe("Stripe price ID to subscribe/upgrade to"),
-	quantity: z.number().positive().describe("Number of seats"),
-	successUrl: z.url().describe("Redirect URL after successful checkout"),
-	cancelUrl: z.url().describe("Redirect URL if checkout is cancelled"),
-	returnUrl: z.string().optional().describe("Return URL for billing portal"),
-	promotionCode: z.string().optional().describe("Promotion code to apply"),
-	subscriptionId: z.string().optional().describe("Subscription ID to upgrade, if none provided assume the active subscription of the user.")
-});
-
-//#endregion
-//#region src/routes/subscriptions.ts
-const subscriptionsRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({ deps, services, config, defineRoute }) => {
-	return [
-		defineRoute({
-			method: "GET",
-			path: "/admin/subscriptions",
-			outputSchema: z.object({ subscriptions: z.array(SubscriptionReponseSchema) }),
-			handler: async (_, { json, error }) => {
-				if (!config.enableAdminRoutes) return error({
+	object: z.literal("price"),
+	active: z.boolean(),
+	billing_scheme: z.string(),
+	created: z.number(),
+	currency: z.string(),
+	custom_unit_amount: z.any().nullable().optional(),
+	deleted: z.void().optional(),
+	livemode: z.boolean(),
+	lookup_key: z.string().nullable().optional(),
+	metadata: z.any(),
+	nickname: z.string().nullable().optional(),
+	product: z.union([z.string(), z.any()]),
+	recurring: z.object({
+		aggregate_usage: z.string().nullable().optional(),
+		interval: z.enum([
+			"day",
+			"week",
+			"month",
+			"year"
+		]),
+		interval_count: z.number(),
+		meter: z.string().nullable().optional(),
+		trial_period_days: z.number().nullable().optional(),
+		usage_type: z.string()
+	}).nullable().optional(),
+	tax_behavior: z.string().nullable().optional(),
+	tiers_mode: z.string().nullable().optional(),
+	transform_quantity: z.any().nullable().optional(),
+	type: z.enum(["one_time", "recurring"]),
+	unit_amount: z.number().nullable().optional(),
+	unit_amount_decimal: z.string().nullable().optional()
+});
+
+//#endregion
+//#region src/routes/prices.ts
+const pricesRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({ deps, config, defineRoute }) => {
+	return [defineRoute({
+		method: "GET",
+		path: "/admin/products/:productId/prices",
+		inputSchema: z.object({
+			limit: z.number().int().positive().max(100).optional().default(50).describe("Number of prices to return (max 100)"),
+			startingAfter: z.string().optional().describe("Price ID to start after for pagination")
+		}),
+		outputSchema: z.object({
+			prices: z.array(PriceResponseSchema),
+			hasMore: z.boolean().describe("Whether there are more items to fetch")
+		}),
+		handler: async ({ pathParams, query }, { json, error }) => {
+			if (!config.enableAdminRoutes) return error({
+				message: "Unauthorized",
+				code: "UNAUTHORIZED"
+			}, 401);
+			const { productId } = pathParams;
+			const limit = Number(query.get("limit")) || void 0;
+			const startingAfter = query.get("startingAfter") || void 0;
+			const prices = await deps.stripe.prices.list({
+				product: productId,
+				limit,
+				starting_after: startingAfter
+			});
+			return json({
+				prices: prices.data,
+				hasMore: prices.has_more
+			});
+		}
+	})];
+});
+
+//#endregion
+//#region src/models/products.ts
+const ProductResponseSchema = z.object({
+	id: z.string(),
+	object: z.literal("product"),
+	active: z.boolean(),
+	created: z.number(),
+	default_price: z.union([z.string(), z.any()]).nullable().optional(),
+	deleted: z.void().optional(),
+	description: z.string().nullable(),
+	images: z.array(z.string()),
+	livemode: z.boolean(),
+	marketing_features: z.array(z.any()),
+	metadata: z.any(),
+	name: z.string(),
+	package_dimensions: z.any().nullable(),
+	shippable: z.boolean().nullable(),
+	statement_descriptor: z.string().nullable().optional(),
+	tax_code: z.union([z.string(), z.any()]).nullable(),
+	type: z.string(),
+	unit_label: z.string().nullable().optional(),
+	updated: z.number(),
+	url: z.string().nullable()
+});
+
+//#endregion
+//#region src/routes/products.ts
+const productsRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({ deps, config, defineRoute }) => {
+	return [defineRoute({
+		method: "GET",
+		path: "/admin/products",
+		inputSchema: z.object({
+			limit: z.number().int().positive().max(100).optional().default(50).describe("Number of products to return (max 100)"),
+			startingAfter: z.string().optional().describe("Product ID to start after for pagination")
+		}),
+		outputSchema: z.object({
+			products: z.array(ProductResponseSchema),
+			hasMore: z.boolean().describe("Whether there are more items to fetch")
+		}),
+		handler: async ({ query }, { json, error }) => {
+			if (!config.enableAdminRoutes) return error({
+				message: "Unauthorized",
+				code: "UNAUTHORIZED"
+			}, 401);
+			const limit = Number(query.get("limit")) || void 0;
+			const startingAfter = query.get("startingAfter") || void 0;
+			const products = await deps.stripe.products.list({
+				limit,
+				starting_after: startingAfter
+			});
+			return json({
+				products: products.data,
+				hasMore: products.has_more
+			});
+		}
+	})];
+});
+
+//#endregion
+//#region src/models/subscriptions.ts
+const SubscriptionReponseSchema = z.object({
+	id: z.string(),
+	stripeSubscriptionId: z.string(),
+	stripeCustomerId: z.string(),
+	stripePriceId: z.string(),
+	referenceId: z.string().nullable(),
+	status: z.enum([
+		"active",
+		"canceled",
+		"incomplete",
+		"incomplete_expired",
+		"past_due",
+		"paused",
+		"trialing",
+		"unpaid"
+	]),
+	periodStart: z.date().nullable(),
+	periodEnd: z.date().nullable(),
+	trialStart: z.date().nullable(),
+	trialEnd: z.date().nullable(),
+	cancelAtPeriodEnd: z.boolean().nullable(),
+	cancelAt: z.date().nullable(),
+	seats: z.number().nullable(),
+	createdAt: z.date(),
+	updatedAt: z.date()
+});
+const SubscriptionUpgradeRequestSchema = z.object({
+	priceId: z.string().describe("Stripe price ID to subscribe/upgrade to"),
+	quantity: z.number().positive().describe("Number of seats"),
+	successUrl: z.url().describe("Redirect URL after successful checkout"),
+	cancelUrl: z.url().describe("Redirect URL if checkout is cancelled"),
+	returnUrl: z.string().optional().describe("Return URL for billing portal"),
+	promotionCode: z.string().optional().describe("Promotion code to apply"),
+	subscriptionId: z.string().optional().describe("Subscription ID to upgrade, if none provided assume the active subscription of the user.")
+});
+
+//#endregion
+//#region src/routes/subscriptions.ts
+const callService = async (handlerTx, call) => {
+	return handlerTx().withServiceCalls(() => [call()]).transform(({ serviceResult: [result] }) => result).execute();
+};
+const subscriptionsRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({ deps, services, config, defineRoute }) => {
+	return [
+		defineRoute({
+			method: "GET",
+			path: "/admin/subscriptions",
+			errorCodes: ["UNAUTHORIZED"],
+			outputSchema: z.object({ subscriptions: z.array(SubscriptionReponseSchema) }),
+			handler: async function(_, { json, error }) {
+				if (!config.enableAdminRoutes) return error({
 					message: "Unauthorized",
 					code: "UNAUTHORIZED"
 				}, 401);
-				return json({ subscriptions: await services.getAllSubscriptions() });
+				return json({ subscriptions: await callService(this.handlerTx, () => services.getAllSubscriptions()) });
 			}
 		}),
 		defineRoute({
@@ -558,13 +474,14 @@ const subscriptionsRoutesFactory = defineRoutes(stripeFragmentDefinition).create
 				"MULTIPLE_ACTIVE_SUBSCRIPTIONS",
 				"NO_ACTIVE_SUBSCRIPTIONS"
 			],
-			handler: async (context, { json, error }) => {
+			handler: async function(context, { json, error }) {
 				const body = await context.input.valid();
 				const entity = await config.resolveEntityFromRequest(context);
 				let customerId = entity.stripeCustomerId;
 				let existingSubscription = null;
-				if (entity.stripeCustomerId) {
-					const existingSubscriptions = await services.getSubscriptionsByStripeCustomerId(entity.stripeCustomerId);
+				const stripeCustomerId = entity.stripeCustomerId;
+				if (stripeCustomerId) {
+					const existingSubscriptions = await callService(this.handlerTx, () => services.getSubscriptionsByStripeCustomerId(stripeCustomerId));
 					let activeSubscriptions = existingSubscriptions.filter((s) => s.status !== "canceled");
 					if (body.subscriptionId) activeSubscriptions = activeSubscriptions.filter((s) => s.id === body.subscriptionId);
 					if (activeSubscriptions.length > 1) return error({
@@ -575,12 +492,17 @@ const subscriptionsRoutesFactory = defineRoutes(stripeFragmentDefinition).create
 						message: "No active subscriptions found for customer",
 						code: "NO_ACTIVE_SUBSCRIPTIONS"
 					}, 400);
-					existingSubscription = activeSubscriptions[0];
-					if (customerId && existingSubscription.stripeCustomerId && existingSubscription.stripeCustomerId !== customerId) return error({
+					const activeSubscription = activeSubscriptions[0];
+					if (!activeSubscription) return error({
+						message: "No active subscriptions found for customer",
+						code: "NO_ACTIVE_SUBSCRIPTIONS"
+					}, 400);
+					existingSubscription = activeSubscription;
+					if (customerId && existingSubscription?.stripeCustomerId && existingSubscription.stripeCustomerId !== customerId) return error({
 						message: "Subsciption being updated does not belong to Stripe Customer that was provided",
 						code: "CUSTOMER_SUBSCRIPTION_MISMATCH"
 					}, 422);
-					customerId = existingSubscription.stripeCustomerId;
+					customerId = activeSubscription.stripeCustomerId;
 				}
 				if (!customerId) {
 					const existingLinkedCustomer = await deps.stripe.customers.search({
@@ -617,7 +539,7 @@ const subscriptionsRoutesFactory = defineRoutes(stripeFragmentDefinition).create
 					});
 					if (promotionCodes.data.length > 0) promotionCodeId = promotionCodes.data[0].id;
 				}
-				if (existingSubscription?.status === "active" || existingSubscription?.status === "trialing") {
+				if (existingSubscription && (existingSubscription.status === "active" || existingSubscription.status === "trialing")) {
 					const stripeSubscription = await deps.stripe.subscriptions.retrieve(existingSubscription.stripeSubscriptionId);
 					try {
 						if (existingSubscription.cancelAt != null) {
@@ -693,14 +615,14 @@ const subscriptionsRoutesFactory = defineRoutes(stripeFragmentDefinition).create
 				"NO_STRIPE_CUSTOMER_LINKED",
 				"MULTIPLE_SUBSCRIPTIONS_FOUND"
 			],
-			handler: async (context, { json, error }) => {
+			handler: async function(context, { json, error }) {
 				const body = await context.input.valid();
 				const { stripeCustomerId } = await config.resolveEntityFromRequest(context);
 				if (!stripeCustomerId) return error({
 					message: "No stripe customer linked to entity",
 					code: "NO_STRIPE_CUSTOMER_LINKED"
 				}, 400);
-				let activeSubscriptions = (await services.getSubscriptionsByStripeCustomerId(stripeCustomerId)).filter((s) => s.status === "active");
+				let activeSubscriptions = (await callService(this.handlerTx, () => services.getSubscriptionsByStripeCustomerId(stripeCustomerId))).filter((s) => s.status === "active");
 				if (body.subscriptionId) activeSubscriptions = activeSubscriptions.filter((s) => s.id === body.subscriptionId);
 				if (activeSubscriptions.length === 0) return error({
 					message: "No active subscription to cancel",
@@ -746,131 +668,259 @@ const subscriptionsRoutesFactory = defineRoutes(stripeFragmentDefinition).create
 });
 
 //#endregion
-//#region src/models/products.ts
-const ProductResponseSchema = z.object({
-	id: z.string(),
-	object: z.literal("product"),
-	active: z.boolean(),
-	created: z.number(),
-	default_price: z.union([z.string(), z.any()]).nullable().optional(),
-	deleted: z.void().optional(),
-	description: z.string().nullable(),
-	images: z.array(z.string()),
-	livemode: z.boolean(),
-	marketing_features: z.array(z.any()),
-	metadata: z.any(),
-	name: z.string(),
-	package_dimensions: z.any().nullable(),
-	shippable: z.boolean().nullable(),
-	statement_descriptor: z.string().nullable().optional(),
-	tax_code: z.union([z.string(), z.any()]).nullable(),
-	type: z.string(),
-	unit_label: z.string().nullable().optional(),
-	updated: z.number(),
-	url: z.string().nullable()
-});
-
-//#endregion
-//#region src/routes/products.ts
-const productsRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({ deps, config, defineRoute }) => {
-	return [defineRoute({
-		method: "GET",
-		path: "/admin/products",
-		inputSchema: z.object({
-			limit: z.number().int().positive().max(100).optional().default(50).describe("Number of products to return (max 100)"),
-			startingAfter: z.string().optional().describe("Product ID to start after for pagination")
-		}),
-		outputSchema: z.object({
-			products: z.array(ProductResponseSchema),
-			hasMore: z.boolean().describe("Whether there are more items to fetch")
-		}),
-		handler: async ({ query }, { json, error }) => {
-			if (!config.enableAdminRoutes) return error({
-				message: "Unauthorized",
-				code: "UNAUTHORIZED"
-			}, 401);
-			const limit = Number(query.get("limit")) || void 0;
-			const startingAfter = query.get("startingAfter") || void 0;
-			const products = await deps.stripe.products.list({
-				limit,
-				starting_after: startingAfter
-			});
-			return json({
-				products: products.data,
-				hasMore: products.has_more
+//#region src/webhook/handlers.ts
+/**
+* Event Handler for checkout.session.completed
+*
+* This handler is ONLY for subscription checkout sessions.
+* Occurs when a Checkout Session has been successfully completed.
+*/
+async function checkoutSessionCompletedHandler({ event, services, deps, handlerTx }) {
+	const checkoutSession = event.data.object;
+	if (checkoutSession.mode !== "subscription") {
+		deps.log.info(`Not handling checkout session with mode ${checkoutSession.mode}: ${event.id}`);
+		return;
+	}
+	const subscriptionId = checkoutSession.subscription;
+	if (typeof subscriptionId !== "string") {
+		deps.log.error("No subscription ID in checkout session");
+		return;
+	}
+	const stripeSubscription = await deps.stripe.subscriptions.retrieve(subscriptionId);
+	const customerId = getId(stripeSubscription.customer);
+	const firstItem = stripeSubscription.items.data[0];
+	if (!firstItem) {
+		deps.log.error("No subscription items found");
+		return;
+	}
+	const referenceId = checkoutSession.metadata?.["referenceId"] || checkoutSession.client_reference_id;
+	const existingSubscriptionId = checkoutSession.metadata?.["subscriptionId"];
+	const subscriptionData = {
+		...stripeSubscriptionToInternalSubscription(stripeSubscription),
+		referenceId: referenceId ?? null
+	};
+	if (existingSubscriptionId) {
+		await handlerTx().withServiceCalls(() => [services.updateSubscription(existingSubscriptionId, subscriptionData)]).execute();
+		deps.log.info(`Updated subscription ${existingSubscriptionId} for customer ${customerId}`);
+		return;
+	}
+	const result = await handlerTx().withServiceCalls(() => [services.getSubscriptionByStripeId(stripeSubscription.id)]).mutate(({ forSchema, serviceIntermediateResult: [existing] }) => {
+		if (existing) return {
+			action: "exists",
+			id: existing.id
+		};
+		const created = forSchema(stripeSchema).create("subscription", subscriptionData);
+		return {
+			action: "created",
+			id: created.externalId
+		};
+	}).execute();
+	if (result.action === "exists") {
+		deps.log.info(`Subscription already exists for Stripe ID ${stripeSubscription.id}`);
+		return;
+	}
+	deps.log.info(`Created subscription ${result.id} for customer ${customerId} (Stripe ID: ${stripeSubscription.id})`);
+}
+/**
+* Event Handler for customer.subscription.paused
+*
+* Occurs whenever a customer’s subscription is paused. Only applies when
+* subscriptions enter status=paused, not when payment collection is paused.
+*
+* PAUSED status: The subscription has ended its trial period without a default
+* payment method and the trial_settings.end_behavior.missing_payment_method is set
+* to pause. Invoices are no longer created for the subscription. After attaching a
+* default payment method to the customer, you can resume the subscription.
+*/
+async function customerSubscriptionPausedHandler(args) {
+	return customerSubscriptionUpdatedHandler(args);
+}
+/**
+* Event Handler for customer.subscription.pending_update_applied
+*
+* Occurs whenever a customer’s subscription’s pending update is applied,
+* and the subscription is updated.
+*/
+async function customerSubscriptionPendingUpdateAppliedHandler(args) {
+	return customerSubscriptionUpdatedHandler(args);
+}
+/**
+* Event Handler for customer.subscription.pending_update_expired
+*
+* Occurs whenever a customer’s subscription’s pending update expires
+* before the related invoice is paid.
+*/
+async function customerSubscriptionPendingUpdateExpiredHandler(args) {
+	return customerSubscriptionUpdatedHandler(args);
+}
+/**
+* Event Handler for customer.subscription.resumed
+*
+* Occurs whenever a customer’s subscription is no longer paused.
+* Only applies when a status=paused subscription is resumed, not when payment
+* collection is resumed.
+*/
+async function customerSubscriptionResumedHandler(args) {
+	return customerSubscriptionUpdatedHandler(args);
+}
+/**
+* Event Handler for customer.subscription.trial_will_end
+*
+* Occurs three days before a subscription's trial period is scheduled to end,
+* or when a trial is ended immediately (using trial_end=now). This event allows
+* you to send reminders or take action before the trial expires.
+*/
+async function customerSubscriptionTrialWillEndHandler(args) {
+	return customerSubscriptionUpdatedHandler(args);
+}
+/**
+* Event Handler for customer.subscription.updated
+*
+* Occurs whenever a subscription changes (e.g., switching from one plan to another,
+* or changing the status from trial to active).
+*/
+async function customerSubscriptionUpdatedHandler({ event, services, deps, handlerTx }) {
+	deps.log.info(`Processing ${event.type}: ${event.id}`);
+	const stripeSubscription = event.data.object;
+	const firstItem = stripeSubscription.items?.data?.[0];
+	if (!firstItem) throw new FragnoApiError({
+		message: "Subscription contains no items",
+		code: "EMPTY_SUBSCRIPTION"
+	}, 400);
+	const customerId = getId(stripeSubscription.customer);
+	const subscriptionPayload = stripeSubscriptionToInternalSubscription(stripeSubscription);
+	const referenceId = stripeSubscription.metadata?.["referenceId"] ?? null;
+	const result = await handlerTx().withServiceCalls(() => [services.getSubscriptionByStripeId(stripeSubscription.id), services.getSubscriptionsByStripeCustomerId(customerId)]).mutate(({ forSchema, serviceIntermediateResult: [byStripeId, byCustomerId] }) => {
+		let subscription = byStripeId;
+		if (!subscription) if (byCustomerId.length > 1) {
+			subscription = byCustomerId.find((sub) => sub.status === "active" || sub.status === "trialing") ?? null;
+			if (!subscription) return { action: "skipped" };
+		} else subscription = byCustomerId[0] ?? null;
+		if (!subscription) {
+			const created = forSchema(stripeSchema).create("subscription", {
+				...subscriptionPayload,
+				referenceId
 			});
+			return {
+				action: "created",
+				id: created.externalId
+			};
 		}
-	})];
-});
-
-//#endregion
-//#region src/models/prices.ts
-const PriceResponseSchema = z.object({
-	id: z.string(),
-	object: z.literal("price"),
-	active: z.boolean(),
-	billing_scheme: z.string(),
-	created: z.number(),
-	currency: z.string(),
-	custom_unit_amount: z.any().nullable().optional(),
-	deleted: z.void().optional(),
-	livemode: z.boolean(),
-	lookup_key: z.string().nullable().optional(),
-	metadata: z.any(),
-	nickname: z.string().nullable().optional(),
-	product: z.union([z.string(), z.any()]),
-	recurring: z.object({
-		aggregate_usage: z.string().nullable().optional(),
-		interval: z.enum([
-			"day",
-			"week",
-			"month",
-			"year"
-		]),
-		interval_count: z.number(),
-		meter: z.string().nullable().optional(),
-		trial_period_days: z.number().nullable().optional(),
-		usage_type: z.string()
-	}).nullable().optional(),
-	tax_behavior: z.string().nullable().optional(),
-	tiers_mode: z.string().nullable().optional(),
-	transform_quantity: z.any().nullable().optional(),
-	type: z.enum(["one_time", "recurring"]),
-	unit_amount: z.number().nullable().optional(),
-	unit_amount_decimal: z.string().nullable().optional()
-});
+		forSchema(stripeSchema).update("subscription", subscription.id, (b) => b.set({
+			...subscriptionPayload,
+			updatedAt: new Date()
+		}));
+		return {
+			action: "updated",
+			id: subscription.id
+		};
+	}).execute();
+	if (result.action === "skipped") {
+		deps.log.warn(`Multiple subscriptions found for customer ${customerId} but none active or trialing`);
+		return;
+	}
+	if (result.action === "created") {
+		deps.log.warn(`No subscription found for Stripe ID ${stripeSubscription.id}, creating new record`);
+		deps.log.info(`Created subscription ${result.id} for customer ${customerId} (Stripe ID: ${stripeSubscription.id})`);
+		return;
+	}
+	deps.log.info(`Updated subscription ${result.id} (Stripe ID: ${stripeSubscription.id})`);
+}
+/**
+* Event Handler for customer.subscription.deleted
+*
+* Occurs whenever a customer's subscription ends.
+*/
+async function customerSubscriptionDeletedHandler({ event, services, deps, handlerTx }) {
+	deps.log.info(`Processing customer.subscription.deleted: ${event.id}`);
+	const stripeSubscription = event.data.object;
+	const result = await handlerTx().withServiceCalls(() => [services.getSubscriptionByStripeId(stripeSubscription.id)]).mutate(({ forSchema, serviceIntermediateResult: [subscription] }) => {
+		if (!subscription) return { action: "missing" };
+		forSchema(stripeSchema).update("subscription", subscription.id, (b) => b.set({
+			status: "canceled",
+			updatedAt: new Date()
+		}));
+		return {
+			action: "canceled",
+			id: subscription.id
+		};
+	}).execute();
+	if (result.action === "missing") {
+		deps.log.warn(`No subscription found for Stripe ID ${stripeSubscription.id}`);
+		return;
+	}
+	deps.log.info(`Marked subscription ${result.id} as canceled (Stripe ID: ${stripeSubscription.id})`);
+}
+const eventToHandler = {
+	"checkout.session.completed": checkoutSessionCompletedHandler,
+	"customer.subscription.deleted": customerSubscriptionDeletedHandler,
+	"customer.subscription.created": customerSubscriptionUpdatedHandler,
+	"customer.subscription.updated": customerSubscriptionUpdatedHandler,
+	"customer.subscription.paused": customerSubscriptionPausedHandler,
+	"customer.subscription.pending_update_applied": customerSubscriptionPendingUpdateAppliedHandler,
+	"customer.subscription.pending_update_expired": customerSubscriptionPendingUpdateExpiredHandler,
+	"customer.subscription.resumed": customerSubscriptionResumedHandler,
+	"customer.subscription.trial_will_end": customerSubscriptionTrialWillEndHandler
+};
 
 //#endregion
-//#region src/routes/prices.ts
-const pricesRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({ deps, config, defineRoute }) => {
+//#region src/routes/webhooks.ts
+const webhookRoutesFactory = defineRoutes(stripeFragmentDefinition).create(({ config, deps, services, defineRoute }) => {
 	return [defineRoute({
-		method: "GET",
-		path: "/admin/products/:productId/prices",
-		inputSchema: z.object({
-			limit: z.number().int().positive().max(100).optional().default(50).describe("Number of prices to return (max 100)"),
-			startingAfter: z.string().optional().describe("Price ID to start after for pagination")
-		}),
-		outputSchema: z.object({
-			prices: z.array(PriceResponseSchema),
-			hasMore: z.boolean().describe("Whether there are more items to fetch")
-		}),
-		handler: async ({ pathParams, query }, { json, error }) => {
-			if (!config.enableAdminRoutes) return error({
-				message: "Unauthorized",
-				code: "UNAUTHORIZED"
-			}, 401);
-			const { productId } = pathParams;
-			const limit = Number(query.get("limit")) || void 0;
-			const startingAfter = query.get("startingAfter") || void 0;
-			const prices = await deps.stripe.prices.list({
-				product: productId,
-				limit,
-				starting_after: startingAfter
-			});
-			return json({
-				prices: prices.data,
-				hasMore: prices.has_more
+		method: "POST",
+		path: "/webhook",
+		outputSchema: z.object({ success: z.boolean() }),
+		errorCodes: [
+			"MISSING_SIGNATURE",
+			"WEBHOOK_SIGNATURE_INVALID",
+			"WEBHOOK_ERROR"
+		],
+		handler: async function({ headers, rawBody }, { json, error }) {
+			const signature = headers.get("stripe-signature");
+			if (!signature) return error({
+				message: "Missing stripe-signature header",
+				code: "MISSING_SIGNATURE"
+			}, 400);
+			if (!rawBody) return error({
+				message: "Missing request body for webhook verification",
+				code: "WEBHOOK_ERROR"
+			}, 400);
+			let event;
+			try {
+				if (typeof deps.stripe.webhooks.constructEventAsync === "function") event = await deps.stripe.webhooks.constructEventAsync(rawBody, signature, config.webhookSecret);
+				else event = deps.stripe.webhooks.constructEvent(rawBody, signature, config.webhookSecret);
+			} catch (err) {
+				if (err instanceof Stripe.errors.StripeSignatureVerificationError) return error({
+					message: `Webhook signature verification failed`,
+					code: "WEBHOOK_SIGNATURE_INVALID"
+				}, 400);
+				throw err;
+			}
+			if (!event) return error({
+				message: "Failed to construct event",
+				code: "WEBHOOK_ERROR"
+			}, 400);
+			if (config.onEvent) {
+				deps.log.info("Running user callback event");
+				await config.onEvent({
+					event,
+					stripeClient: deps.stripe
+				});
+			}
+			const eventHandler = eventToHandler[event.type];
+			if (!eventHandler) {
+				deps.log.info(`Webhook event ${event.type}: ${event.id} ignored`);
+				return json({ success: true });
+			}
+			deps.log.info(`Executing event handler for ${event.type}: ${event.id}`);
+			await eventHandler({
+				event,
+				services,
+				deps,
+				config,
+				handlerTx: this.handlerTx
 			});
+			return json({ success: true });
 		}
 	})];
 });