alepha 0.19.0 → 0.19.2

package/dist/billing/index.js

@@ -0,0 +1,713 @@
+import { $inject, $module, Alepha, AlephaError, t } from "alepha";
+import { $secure } from "alepha/security";
+import { $action, okSchema } from "alepha/server";
+import { $entity, $repository, db, pageQuerySchema } from "alepha/orm";
+import { $job } from "alepha/api/jobs";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { randomUUID } from "node:crypto";
+//#region ../../src/billing/entities/paymentIntents.ts
+const paymentIntents = $entity({
+	name: "payment_intents",
+	schema: t.object({
+		id: db.primaryKey(t.uuid()),
+		version: db.version(),
+		createdAt: db.createdAt(),
+		updatedAt: db.updatedAt(),
+		organizationId: db.organization(),
+		amount: t.integer(),
+		currency: t.text({ size: "short" }),
+		status: t.enum([
+			"created",
+			"processing",
+			"authorized",
+			"captured",
+			"voided",
+			"failed",
+			"cancelled",
+			"refunded",
+			"expired"
+		]),
+		providerRef: t.optional(t.text()),
+		providerRaw: t.optional(t.json()),
+		metadata: t.optional(t.json()),
+		paymentMethodId: t.optional(t.uuid()),
+		userId: t.optional(t.uuid())
+	}),
+	indexes: [
+		"status",
+		"organizationId",
+		"userId",
+		"createdAt"
+	]
+});
+//#endregion
+//#region ../../src/billing/schemas/intentSchemas.ts
+const createIntentSchema = t.object({
+	amount: t.integer({ minimum: 1 }),
+	currency: t.text({ size: "short" }),
+	metadata: t.optional(t.json()),
+	paymentMethodId: t.optional(t.uuid())
+});
+const createCheckoutSchema = t.object({
+	intentId: t.uuid(),
+	returnUrl: t.text(),
+	authorize: t.optional(t.boolean())
+});
+const checkoutResponseSchema = t.object({
+	url: t.text(),
+	intentId: t.text()
+});
+const captureIntentSchema = t.object({ amount: t.optional(t.integer({ minimum: 1 })) });
+const refundIntentSchema = t.object({
+	amount: t.integer({ minimum: 1 }),
+	reason: t.optional(t.text())
+});
+const recordCashSchema = t.object({
+	amount: t.integer({ minimum: 1 }),
+	currency: t.text({ size: "short" }),
+	metadata: t.optional(t.json())
+});
+const intentQuerySchema = t.extend(pageQuerySchema, {
+	status: t.optional(t.text({ description: "Filter by status" })),
+	userId: t.optional(t.uuid({ description: "Filter by user ID" }))
+});
+const intentResourceSchema = paymentIntents.schema;
+//#endregion
+//#region ../../src/billing/entities/refunds.ts
+const refunds = $entity({
+	name: "refunds",
+	schema: t.object({
+		id: db.primaryKey(t.uuid()),
+		version: db.version(),
+		createdAt: db.createdAt(),
+		updatedAt: db.updatedAt(),
+		organizationId: db.organization(),
+		intentId: t.uuid(),
+		amount: t.integer(),
+		currency: t.text({ size: "short" }),
+		status: t.enum([
+			"pending",
+			"processing",
+			"completed",
+			"failed"
+		]),
+		reason: t.optional(t.text()),
+		providerRef: t.optional(t.text())
+	}),
+	indexes: [
+		"intentId",
+		"organizationId",
+		"status"
+	]
+});
+//#endregion
+//#region ../../src/billing/schemas/refundSchemas.ts
+const refundResourceSchema = refunds.schema;
+//#endregion
+//#region ../../src/billing/errors/BillingError.ts
+var BillingError = class extends AlephaError {
+	status = 400;
+};
+//#endregion
+//#region ../../src/billing/providers/BillingProvider.ts
+var BillingProvider = class {};
+//#endregion
+//#region ../../src/billing/services/BillingService.ts
+var BillingService = class {
+	alepha = $inject(Alepha);
+	log = $logger();
+	dateTime = $inject(DateTimeProvider);
+	provider = $inject(BillingProvider);
+	intentRepo = $repository(paymentIntents);
+	refundRepo = $repository(refunds);
+	/**
+	* Expires stale payment intents that have been in "processing" status
+	* for more than 30 minutes. Runs every 15 minutes.
+	*/
+	expireStaleIntents = $job({
+		cron: "*/15 * * * *",
+		handler: async () => {
+			const cutoff = this.dateTime.now().subtract(30, "minutes").toISOString();
+			const stale = await this.intentRepo.findMany({ where: {
+				status: { eq: "processing" },
+				createdAt: { lt: cutoff }
+			} });
+			for (const intent of stale) {
+				if (intent.providerRef) try {
+					await this.provider.expireSession(intent.providerRef);
+				} catch (error) {
+					this.log.warn(`Failed to expire session for intent ${intent.id}`, error);
+				}
+				await this.intentRepo.updateById(intent.id, { status: "expired" });
+				this.log.info(`Expired stale intent ${intent.id}`);
+			}
+		}
+	});
+	/**
+	* Create a new payment intent in "created" status.
+	*/
+	async createIntent(amount, currency, metadata, options) {
+		return await this.intentRepo.create({
+			amount,
+			currency,
+			status: "created",
+			metadata,
+			paymentMethodId: options?.paymentMethodId,
+			userId: options?.userId
+		});
+	}
+	/**
+	* Create a checkout session with the payment provider and
+	* transition the intent to "processing".
+	*/
+	async createSession(intentId, returnUrl, authorize) {
+		const intent = await this.getIntent(intentId);
+		this.assertStatus(intent, "created", "createSession");
+		const result = await this.provider.createSession(intent, {
+			returnUrl,
+			authorize
+		});
+		await this.intentRepo.updateById(intent.id, {
+			status: "processing",
+			providerRef: result.providerRef
+		});
+		return {
+			url: result.url,
+			intentId: intent.id
+		};
+	}
+	/**
+	* Handle an incoming webhook from the payment provider.
+	*/
+	async handleWebhook(request) {
+		const event = await this.provider.parseWebhook(request);
+		const intents = await this.intentRepo.findMany({
+			where: { providerRef: { eq: event.providerRef } },
+			limit: 1
+		});
+		if (intents.length === 0) {
+			this.log.warn(`Webhook for unknown providerRef: ${event.providerRef}`);
+			return;
+		}
+		const intent = intents[0];
+		await this.handleWebhookEvent(intent.id, event.status, event.raw);
+	}
+	/**
+	* Process a webhook event by updating the intent status and emitting
+	* the corresponding billing event.
+	*/
+	async handleWebhookEvent(intentId, status, raw) {
+		const intent = await this.getIntent(intentId);
+		const eventMap = {
+			authorized: "billing:authorized",
+			captured: "billing:captured",
+			failed: "billing:failed"
+		};
+		if (!(status in eventMap)) {
+			this.log.warn(`Unknown webhook status: ${status}`);
+			return;
+		}
+		const webhookStatus = status;
+		await this.intentRepo.updateById(intent.id, {
+			status: webhookStatus,
+			providerRaw: raw
+		});
+		await this.alepha.events.emit(eventMap[webhookStatus], {
+			intentId: intent.id,
+			amount: intent.amount,
+			currency: intent.currency,
+			metadata: intent.metadata
+		});
+	}
+	/**
+	* Capture a previously authorized payment. Optionally specify a different
+	* amount for partial capture.
+	*/
+	async capture(intentId, finalAmount) {
+		const intent = await this.getIntent(intentId);
+		this.assertStatus(intent, "authorized", "capture");
+		const amount = finalAmount ?? intent.amount;
+		if (intent.providerRef) await this.provider.capturePayment(intent.providerRef, amount);
+		const updated = await this.intentRepo.updateById(intent.id, {
+			status: "captured",
+			amount
+		});
+		await this.alepha.events.emit("billing:captured", {
+			intentId: intent.id,
+			amount,
+			currency: intent.currency,
+			metadata: intent.metadata
+		});
+		return updated;
+	}
+	/**
+	* Void a previously authorized payment before capture.
+	*/
+	async void(intentId) {
+		const intent = await this.getIntent(intentId);
+		this.assertStatus(intent, "authorized", "void");
+		if (intent.providerRef) await this.provider.voidPayment(intent.providerRef);
+		const updated = await this.intentRepo.updateById(intent.id, { status: "voided" });
+		await this.alepha.events.emit("billing:voided", {
+			intentId: intent.id,
+			amount: intent.amount,
+			currency: intent.currency,
+			metadata: intent.metadata
+		});
+		return updated;
+	}
+	/**
+	* Refund a captured payment (partial or full).
+	*/
+	async refund(intentId, amount, reason) {
+		const intent = await this.getIntent(intentId);
+		this.assertStatus(intent, "captured", "refund");
+		let refundProviderRef;
+		if (intent.providerRef) refundProviderRef = (await this.provider.refundPayment(intent.providerRef, amount)).providerRef;
+		const refund = await this.refundRepo.create({
+			intentId: intent.id,
+			organizationId: intent.organizationId,
+			amount,
+			currency: intent.currency,
+			status: "completed",
+			reason,
+			providerRef: refundProviderRef
+		});
+		await this.intentRepo.updateById(intent.id, { status: "refunded" });
+		await this.alepha.events.emit("billing:refunded", {
+			intentId: intent.id,
+			refundId: refund.id,
+			amount,
+			currency: intent.currency,
+			metadata: intent.metadata
+		});
+		return refund;
+	}
+	/**
+	* Record a cash or offline payment directly as captured,
+	* bypassing the checkout flow.
+	*/
+	async recordCashPayment(amount, currency, metadata) {
+		const intent = await this.intentRepo.create({
+			amount,
+			currency,
+			status: "captured",
+			metadata
+		});
+		await this.alepha.events.emit("billing:captured", {
+			intentId: intent.id,
+			amount,
+			currency,
+			metadata
+		});
+		return intent;
+	}
+	/**
+	* Cancel a payment intent that has not yet entered processing.
+	*/
+	async cancel(intentId) {
+		const intent = await this.getIntent(intentId);
+		this.assertStatus(intent, "created", "cancel");
+		return await this.intentRepo.updateById(intent.id, { status: "cancelled" });
+	}
+	/**
+	* Get a payment intent by ID. Throws NotFoundError if not found.
+	*/
+	async getIntent(intentId) {
+		return await this.intentRepo.getById(intentId);
+	}
+	/**
+	* Find payment intents with optional filters and pagination.
+	*/
+	async findIntents(query) {
+		const where = this.intentRepo.createQueryWhere();
+		if (query.status) where.status = { eq: query.status };
+		if (query.userId) where.userId = { eq: query.userId };
+		return await this.intentRepo.paginate(query, { where }, { count: true });
+	}
+	assertStatus(intent, expected, operation) {
+		if (intent.status !== expected) throw new BillingError(`Cannot ${operation}: intent ${intent.id} is '${intent.status}', expected '${expected}'`);
+	}
+};
+//#endregion
+//#region ../../src/billing/controllers/AdminBillingController.ts
+var AdminBillingController = class {
+	url = "/admin/billing";
+	group = "admin:billing";
+	billing = $inject(BillingService);
+	/**
+	* List payment intents with pagination and filtering.
+	*/
+	listIntents = $action({
+		path: `${this.url}/intents`,
+		group: this.group,
+		use: [$secure({ permissions: ["billing:read"] })],
+		description: "List payment intents",
+		schema: {
+			query: intentQuerySchema,
+			response: t.page(intentResourceSchema)
+		},
+		handler: ({ query }) => this.billing.findIntents(query)
+	});
+	/**
+	* Get a payment intent by ID.
+	*/
+	getIntent = $action({
+		path: `${this.url}/intents/:id`,
+		group: this.group,
+		use: [$secure({ permissions: ["billing:read"] })],
+		description: "Get payment intent details",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: intentResourceSchema
+		},
+		handler: ({ params }) => this.billing.getIntent(params.id)
+	});
+	/**
+	* Capture an authorized intent.
+	*/
+	captureIntent = $action({
+		method: "POST",
+		path: `${this.url}/intents/:id/capture`,
+		group: this.group,
+		use: [$secure({ permissions: ["billing:write"] })],
+		description: "Capture an authorized payment intent",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			body: captureIntentSchema,
+			response: intentResourceSchema
+		},
+		handler: ({ params, body }) => this.billing.capture(params.id, body.amount)
+	});
+	/**
+	* Void an authorized intent.
+	*/
+	voidIntent = $action({
+		method: "POST",
+		path: `${this.url}/intents/:id/void`,
+		group: this.group,
+		use: [$secure({ permissions: ["billing:write"] })],
+		description: "Void an authorized payment intent",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: intentResourceSchema
+		},
+		handler: ({ params }) => this.billing.void(params.id)
+	});
+	/**
+	* Refund a captured intent.
+	*/
+	refundIntent = $action({
+		method: "POST",
+		path: `${this.url}/intents/:id/refund`,
+		group: this.group,
+		use: [$secure({ permissions: ["billing:write"] })],
+		description: "Issue partial or full refund",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			body: refundIntentSchema,
+			response: refundResourceSchema
+		},
+		handler: ({ params, body }) => this.billing.refund(params.id, body.amount, body.reason)
+	});
+	/**
+	* Cancel a created intent.
+	*/
+	cancelIntent = $action({
+		method: "POST",
+		path: `${this.url}/intents/:id/cancel`,
+		group: this.group,
+		use: [$secure({ permissions: ["billing:write"] })],
+		description: "Cancel a created payment intent",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: intentResourceSchema
+		},
+		handler: ({ params }) => this.billing.cancel(params.id)
+	});
+	/**
+	* Record a cash payment.
+	*/
+	recordCash = $action({
+		method: "POST",
+		path: `${this.url}/cash`,
+		group: this.group,
+		use: [$secure({ permissions: ["billing:write"] })],
+		description: "Record a cash payment",
+		schema: {
+			body: recordCashSchema,
+			response: intentResourceSchema
+		},
+		handler: ({ body }) => this.billing.recordCashPayment(body.amount, body.currency, body.metadata)
+	});
+	/**
+	* PSP webhook endpoint (not under /admin, no auth — verified by provider).
+	*/
+	webhook = $action({
+		method: "POST",
+		path: "/billing/webhook",
+		group: this.group,
+		description: "PSP webhook endpoint",
+		schema: { response: okSchema },
+		handler: async (request) => {
+			await this.billing.handleWebhook(request.raw.web.req);
+			return { ok: true };
+		}
+	});
+};
+//#endregion
+//#region ../../src/billing/entities/paymentMethods.ts
+const paymentMethods = $entity({
+	name: "payment_methods",
+	schema: t.object({
+		id: db.primaryKey(t.uuid()),
+		version: db.version(),
+		createdAt: db.createdAt(),
+		updatedAt: db.updatedAt(),
+		organizationId: db.organization(),
+		userId: t.uuid(),
+		type: t.text({ size: "short" }),
+		brand: t.optional(t.text({ size: "short" })),
+		last4: t.optional(t.text({ size: "short" })),
+		expMonth: t.optional(t.integer()),
+		expYear: t.optional(t.integer()),
+		isDefault: t.boolean(),
+		providerRef: t.text()
+	}),
+	indexes: ["userId", "organizationId"]
+});
+//#endregion
+//#region ../../src/billing/schemas/paymentMethodSchemas.ts
+const addPaymentMethodSchema = t.object({ token: t.text() });
+const paymentMethodResourceSchema = paymentMethods.schema;
+//#endregion
+//#region ../../src/billing/services/PaymentMethodService.ts
+var PaymentMethodService = class {
+	log = $logger();
+	provider = $inject(BillingProvider);
+	methodRepo = $repository(paymentMethods);
+	async addPaymentMethod(userId, organizationId, token) {
+		const result = await this.provider.createPaymentMethod(userId, token);
+		const existing = await this.methodRepo.findMany({ where: { userId: { eq: userId } } });
+		return await this.methodRepo.create({
+			userId,
+			organizationId,
+			type: result.type,
+			brand: result.brand,
+			last4: result.last4,
+			expMonth: result.expMonth,
+			expYear: result.expYear,
+			isDefault: existing.length === 0,
+			providerRef: result.providerRef
+		});
+	}
+	async listPaymentMethods(userId) {
+		return await this.methodRepo.findMany({ where: { userId: { eq: userId } } });
+	}
+	async removePaymentMethod(methodId, userId) {
+		const method = await this.methodRepo.getById(methodId);
+		if (method.userId !== userId) throw new BillingError("Cannot remove another user's payment method");
+		await this.provider.deletePaymentMethod(method.providerRef);
+		await this.methodRepo.deleteById(method.id);
+	}
+	async setDefault(methodId, userId) {
+		const method = await this.methodRepo.getById(methodId);
+		if (method.userId !== userId) throw new BillingError("Cannot modify another user's payment method");
+		const userMethods = await this.methodRepo.findMany({ where: { userId: { eq: userId } } });
+		for (const m of userMethods) if (m.isDefault) await this.methodRepo.updateById(m.id, { isDefault: false });
+		return await this.methodRepo.updateById(method.id, { isDefault: true });
+	}
+};
+//#endregion
+//#region ../../src/billing/controllers/BillingController.ts
+var BillingController = class {
+	url = "/billing";
+	group = "billing";
+	billing = $inject(BillingService);
+	paymentMethods = $inject(PaymentMethodService);
+	/**
+	* List the current user's saved payment methods.
+	*/
+	listPaymentMethods = $action({
+		path: `${this.url}/payment-methods`,
+		group: this.group,
+		use: [$secure()],
+		description: "List current user's saved payment methods",
+		schema: { response: t.array(paymentMethodResourceSchema) },
+		handler: ({ user }) => this.paymentMethods.listPaymentMethods(user.id)
+	});
+	/**
+	* Add a new payment method.
+	*/
+	addPaymentMethod = $action({
+		method: "POST",
+		path: `${this.url}/payment-methods`,
+		group: this.group,
+		use: [$secure()],
+		description: "Tokenize and store a new payment method",
+		schema: {
+			body: addPaymentMethodSchema,
+			response: paymentMethodResourceSchema
+		},
+		handler: ({ body, user }) => this.paymentMethods.addPaymentMethod(user.id, user.organization, body.token)
+	});
+	/**
+	* Remove a payment method.
+	*/
+	removePaymentMethod = $action({
+		method: "DELETE",
+		path: `${this.url}/payment-methods/:id`,
+		group: this.group,
+		use: [$secure()],
+		description: "Remove own payment method",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: okSchema
+		},
+		handler: async ({ params, user }) => {
+			await this.paymentMethods.removePaymentMethod(params.id, user.id);
+			return {
+				ok: true,
+				id: params.id
+			};
+		}
+	});
+	/**
+	* Set a payment method as default.
+	*/
+	setDefaultPaymentMethod = $action({
+		method: "PATCH",
+		path: `${this.url}/payment-methods/:id/default`,
+		group: this.group,
+		use: [$secure()],
+		description: "Set as default payment method",
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: paymentMethodResourceSchema
+		},
+		handler: ({ params, user }) => this.paymentMethods.setDefault(params.id, user.id)
+	});
+	/**
+	* Create a checkout session.
+	*/
+	createCheckout = $action({
+		method: "POST",
+		path: `${this.url}/checkout`,
+		group: this.group,
+		use: [$secure()],
+		description: "Create checkout session and return URL",
+		schema: {
+			body: createCheckoutSchema,
+			response: checkoutResponseSchema
+		},
+		handler: ({ body }) => this.billing.createSession(body.intentId, body.returnUrl, body.authorize)
+	});
+};
+//#endregion
+//#region ../../src/billing/providers/MemoryBillingProvider.ts
+var MemoryBillingProvider = class {
+	charges = /* @__PURE__ */ new Map();
+	refundRecords = /* @__PURE__ */ new Map();
+	methods = /* @__PURE__ */ new Map();
+	expiredSessions = /* @__PURE__ */ new Set();
+	async createSession(intent, options) {
+		const providerRef = `mem_session_${randomUUID()}`;
+		const status = options.authorize ? "authorized" : "captured";
+		this.charges.set(providerRef, {
+			providerRef,
+			amount: intent.amount,
+			status
+		});
+		return {
+			url: `/billing/mock-checkout/${intent.id}`,
+			providerRef
+		};
+	}
+	async capturePayment(providerRef, amount) {
+		const charge = this.charges.get(providerRef);
+		if (charge) {
+			charge.status = "captured";
+			charge.amount = amount;
+		}
+	}
+	async voidPayment(providerRef) {
+		const charge = this.charges.get(providerRef);
+		if (charge) charge.status = "voided";
+	}
+	async refundPayment(providerRef, amount) {
+		const refundRef = `mem_refund_${randomUUID()}`;
+		this.refundRecords.set(refundRef, {
+			providerRef: refundRef,
+			chargeRef: providerRef,
+			amount
+		});
+		return { providerRef: refundRef };
+	}
+	async parseWebhook(request) {
+		const body = await request.json();
+		return {
+			providerRef: body.providerRef,
+			status: body.status,
+			raw: body
+		};
+	}
+	async createPaymentMethod(userId, token) {
+		const providerRef = `mem_pm_${randomUUID()}`;
+		const result = {
+			providerRef,
+			type: "card",
+			brand: "visa",
+			last4: "4242",
+			expMonth: 12,
+			expYear: 2030
+		};
+		this.methods.set(providerRef, result);
+		return result;
+	}
+	async deletePaymentMethod(providerRef) {
+		this.methods.delete(providerRef);
+	}
+	async expireSession(providerRef) {
+		this.expiredSessions.add(providerRef);
+	}
+	wasCharged(providerRef) {
+		return this.charges.get(providerRef)?.status === "captured";
+	}
+	wasRefunded(providerRef) {
+		return Array.from(this.refundRecords.values()).some((r) => r.chargeRef === providerRef);
+	}
+	wasExpired(providerRef) {
+		return this.expiredSessions.has(providerRef);
+	}
+	getCharges() {
+		return Array.from(this.charges.values());
+	}
+	getRefunds() {
+		return Array.from(this.refundRecords.values());
+	}
+};
+//#endregion
+//#region ../../src/billing/index.ts
+const AlephaBilling = $module({
+	name: "alepha.billing",
+	services: [
+		AdminBillingController,
+		BillingController,
+		BillingProvider,
+		MemoryBillingProvider,
+		BillingService,
+		PaymentMethodService
+	],
+	register: (alepha) => {
+		alepha.with({
+			optional: true,
+			provide: BillingProvider,
+			use: MemoryBillingProvider
+		});
+	}
+});
+//#endregion
+export { AdminBillingController, AlephaBilling, BillingController, BillingError, BillingProvider, BillingService, MemoryBillingProvider, PaymentMethodService, addPaymentMethodSchema, captureIntentSchema, checkoutResponseSchema, createCheckoutSchema, createIntentSchema, intentQuerySchema, intentResourceSchema, paymentIntents, paymentMethodResourceSchema, paymentMethods, recordCashSchema, refundIntentSchema, refundResourceSchema, refunds };
+
+//# sourceMappingURL=index.js.map