@86d-app/payments 0.0.3

package/src/schema.ts

@@ -0,0 +1,97 @@
+import type { ModuleSchema } from "@86d-app/core";
+
+export const paymentsSchema = {
+	paymentIntent: {
+		fields: {
+			id: { type: "string", required: true },
+			/** Provider-assigned intent ID (e.g. Stripe's pi_xxx) */
+			providerIntentId: { type: "string", required: false },
+			customerId: { type: "string", required: false },
+			email: { type: "string", required: false },
+			/** Amount in smallest currency unit (e.g. cents) */
+			amount: { type: "number", required: true },
+			currency: { type: "string", required: true, defaultValue: "USD" },
+			status: {
+				type: [
+					"pending",
+					"processing",
+					"succeeded",
+					"failed",
+					"cancelled",
+					"refunded",
+				],
+				required: true,
+				defaultValue: "pending",
+			},
+			paymentMethodId: { type: "string", required: false },
+			orderId: { type: "string", required: false },
+			checkoutSessionId: { type: "string", required: false },
+			metadata: { type: "json", required: false, defaultValue: {} },
+			providerMetadata: { type: "json", required: false, defaultValue: {} },
+			createdAt: {
+				type: "date",
+				required: true,
+				defaultValue: () => new Date(),
+			},
+			updatedAt: {
+				type: "date",
+				required: true,
+				defaultValue: () => new Date(),
+				onUpdate: () => new Date(),
+			},
+		},
+	},
+	paymentMethod: {
+		fields: {
+			id: { type: "string", required: true },
+			customerId: { type: "string", required: true },
+			/** Provider-assigned method ID (e.g. Stripe's pm_xxx) */
+			providerMethodId: { type: "string", required: true },
+			/** card | bank_transfer | wallet */
+			type: { type: "string", required: true, defaultValue: "card" },
+			last4: { type: "string", required: false },
+			brand: { type: "string", required: false },
+			expiryMonth: { type: "number", required: false },
+			expiryYear: { type: "number", required: false },
+			isDefault: { type: "boolean", required: true, defaultValue: false },
+			createdAt: {
+				type: "date",
+				required: true,
+				defaultValue: () => new Date(),
+			},
+			updatedAt: {
+				type: "date",
+				required: true,
+				defaultValue: () => new Date(),
+				onUpdate: () => new Date(),
+			},
+		},
+	},
+	refund: {
+		fields: {
+			id: { type: "string", required: true },
+			paymentIntentId: { type: "string", required: true },
+			/** Provider-assigned refund ID */
+			providerRefundId: { type: "string", required: true },
+			/** Refund amount in smallest currency unit */
+			amount: { type: "number", required: true },
+			reason: { type: "string", required: false },
+			status: {
+				type: ["pending", "succeeded", "failed"],
+				required: true,
+				defaultValue: "pending",
+			},
+			createdAt: {
+				type: "date",
+				required: true,
+				defaultValue: () => new Date(),
+			},
+			updatedAt: {
+				type: "date",
+				required: true,
+				defaultValue: () => new Date(),
+				onUpdate: () => new Date(),
+			},
+		},
+	},
+} satisfies ModuleSchema;

package/src/service-impl.ts

@@ -0,0 +1,331 @@
+import type { ModuleDataService } from "@86d-app/core";
+import type {
+	PaymentController,
+	PaymentIntent,
+	PaymentIntentStatus,
+	PaymentMethod,
+	PaymentProvider,
+	Refund,
+} from "./service";
+
+export function createPaymentController(
+	data: ModuleDataService,
+	provider?: PaymentProvider,
+): PaymentController {
+	return {
+		async createIntent(params) {
+			const id = crypto.randomUUID();
+			const now = new Date();
+
+			let providerIntentId: string | undefined;
+			let providerMetadata: Record<string, unknown> = {};
+			let status: PaymentIntentStatus = "pending";
+
+			if (provider) {
+				const result = await provider.createIntent({
+					amount: params.amount,
+					currency: params.currency ?? "USD",
+					metadata: params.metadata,
+				});
+				providerIntentId = result.providerIntentId;
+				providerMetadata = result.providerMetadata ?? {};
+				status = result.status;
+			}
+
+			const intent: PaymentIntent = {
+				id,
+				providerIntentId,
+				customerId: params.customerId,
+				email: params.email,
+				amount: params.amount,
+				currency: params.currency ?? "USD",
+				status,
+				orderId: params.orderId,
+				checkoutSessionId: params.checkoutSessionId,
+				metadata: params.metadata ?? {},
+				providerMetadata,
+				createdAt: now,
+				updatedAt: now,
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("paymentIntent", id, intent as Record<string, any>);
+			return intent;
+		},
+
+		async getIntent(id) {
+			const raw = await data.get("paymentIntent", id);
+			if (!raw) return null;
+			return raw as unknown as PaymentIntent;
+		},
+
+		async confirmIntent(id) {
+			const existing = await data.get("paymentIntent", id);
+			if (!existing) return null;
+			const intent = existing as unknown as PaymentIntent;
+			if (intent.status === "succeeded") return intent;
+
+			let newStatus: PaymentIntentStatus = "succeeded";
+			let newProviderMetadata = intent.providerMetadata;
+
+			if (provider && intent.providerIntentId) {
+				const result = await provider.confirmIntent(intent.providerIntentId);
+				newStatus = result.status === "succeeded" ? "succeeded" : result.status;
+				newProviderMetadata = result.providerMetadata ?? newProviderMetadata;
+			}
+
+			const updated: PaymentIntent = {
+				...intent,
+				status: newStatus,
+				providerMetadata: newProviderMetadata,
+				updatedAt: new Date(),
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("paymentIntent", id, updated as Record<string, any>);
+			return updated;
+		},
+
+		async cancelIntent(id) {
+			const existing = await data.get("paymentIntent", id);
+			if (!existing) return null;
+			const intent = existing as unknown as PaymentIntent;
+			if (intent.status === "cancelled") return intent;
+
+			let newProviderMetadata = intent.providerMetadata;
+
+			if (provider && intent.providerIntentId) {
+				const result = await provider.cancelIntent(intent.providerIntentId);
+				newProviderMetadata = result.providerMetadata ?? newProviderMetadata;
+			}
+
+			const updated: PaymentIntent = {
+				...intent,
+				status: "cancelled",
+				providerMetadata: newProviderMetadata,
+				updatedAt: new Date(),
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("paymentIntent", id, updated as Record<string, any>);
+			return updated;
+		},
+
+		async listIntents(params) {
+			// Push available filters to where clause
+			// biome-ignore lint/suspicious/noExplicitAny: JSONB where filter
+			const where: Record<string, any> = {};
+			if (params?.customerId) where.customerId = params.customerId;
+			if (params?.status) where.status = params.status;
+			if (params?.orderId) where.orderId = params.orderId;
+
+			const all = await data.findMany("paymentIntent", {
+				...(Object.keys(where).length > 0 ? { where } : {}),
+				...(params?.take !== undefined ? { take: params.take } : {}),
+				...(params?.skip !== undefined ? { skip: params.skip } : {}),
+			});
+			return all as unknown as PaymentIntent[];
+		},
+
+		async savePaymentMethod(params) {
+			const id = crypto.randomUUID();
+			const now = new Date();
+
+			// If isDefault is set, clear other defaults for this customer
+			if (params.isDefault) {
+				const existing = await data.findMany("paymentMethod", {
+					where: { customerId: params.customerId, isDefault: true },
+				});
+				const methods = existing as unknown as PaymentMethod[];
+				for (const m of methods) {
+					const cleared: PaymentMethod = {
+						...m,
+						isDefault: false,
+						updatedAt: now,
+					};
+					await data.upsert(
+						"paymentMethod",
+						m.id,
+						// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+						cleared as unknown as Record<string, any>,
+					);
+				}
+			}
+
+			const method: PaymentMethod = {
+				id,
+				customerId: params.customerId,
+				providerMethodId: params.providerMethodId,
+				type: params.type ?? "card",
+				last4: params.last4,
+				brand: params.brand,
+				expiryMonth: params.expiryMonth,
+				expiryYear: params.expiryYear,
+				isDefault: params.isDefault ?? false,
+				createdAt: now,
+				updatedAt: now,
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("paymentMethod", id, method as Record<string, any>);
+			return method;
+		},
+
+		async getPaymentMethod(id) {
+			const raw = await data.get("paymentMethod", id);
+			if (!raw) return null;
+			return raw as unknown as PaymentMethod;
+		},
+
+		async listPaymentMethods(customerId) {
+			const all = await data.findMany("paymentMethod", {
+				where: { customerId },
+			});
+			return all as unknown as PaymentMethod[];
+		},
+
+		async deletePaymentMethod(id) {
+			const existing = await data.get("paymentMethod", id);
+			if (!existing) return false;
+			await data.delete("paymentMethod", id);
+			return true;
+		},
+
+		async createRefund(params) {
+			const intent = await data.get("paymentIntent", params.intentId);
+			if (!intent) throw new Error("Payment intent not found");
+			const pi = intent as unknown as PaymentIntent;
+
+			const refundAmount = params.amount ?? pi.amount;
+
+			let providerRefundId: string;
+			let refundStatus: Refund["status"] = "succeeded";
+
+			if (provider && pi.providerIntentId) {
+				const result = await provider.createRefund({
+					providerIntentId: pi.providerIntentId,
+					amount: params.amount,
+					reason: params.reason,
+				});
+				providerRefundId = result.providerRefundId;
+				refundStatus = result.status;
+			} else if (pi.providerIntentId && !provider) {
+				throw new Error(
+					"Cannot refund: payment was created through a provider but no provider is configured",
+				);
+			} else {
+				// Local-only intent (no external provider was used)
+				providerRefundId = `local_re_${crypto.randomUUID()}`;
+			}
+
+			const id = crypto.randomUUID();
+			const now = new Date();
+			const refund: Refund = {
+				id,
+				paymentIntentId: params.intentId,
+				providerRefundId,
+				amount: refundAmount,
+				reason: params.reason,
+				status: refundStatus,
+				createdAt: now,
+				updatedAt: now,
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("refund", id, refund as Record<string, any>);
+
+			// Mark intent as refunded
+			const updatedIntent: PaymentIntent = {
+				...pi,
+				status: "refunded",
+				updatedAt: now,
+			};
+			await data.upsert(
+				"paymentIntent",
+				params.intentId,
+				// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+				updatedIntent as unknown as Record<string, any>,
+			);
+
+			return refund;
+		},
+
+		async getRefund(id) {
+			const raw = await data.get("refund", id);
+			if (!raw) return null;
+			return raw as unknown as Refund;
+		},
+
+		async listRefunds(intentId) {
+			const all = await data.findMany("refund", {
+				where: { paymentIntentId: intentId },
+			});
+			return all as unknown as Refund[];
+		},
+
+		async handleWebhookEvent(params) {
+			const all = await data.findMany("paymentIntent", {
+				where: { providerIntentId: params.providerIntentId },
+				take: 1,
+			});
+			const intents = all as unknown as PaymentIntent[];
+			if (intents.length === 0) return null;
+
+			const intent = intents[0];
+			if (intent.status === params.status) return intent;
+
+			const updated: PaymentIntent = {
+				...intent,
+				status: params.status,
+				providerMetadata: {
+					...intent.providerMetadata,
+					...(params.providerMetadata ?? {}),
+				},
+				updatedAt: new Date(),
+			};
+			await data.upsert(
+				"paymentIntent",
+				intent.id,
+				// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+				updated as Record<string, any>,
+			);
+			return updated;
+		},
+
+		async handleWebhookRefund(params) {
+			const all = await data.findMany("paymentIntent", {
+				where: { providerIntentId: params.providerIntentId },
+				take: 1,
+			});
+			const intents = all as unknown as PaymentIntent[];
+			if (intents.length === 0) return null;
+
+			const intent = intents[0];
+			const now = new Date();
+			const refundAmount = params.amount ?? intent.amount;
+
+			const refundId = crypto.randomUUID();
+			const refund: Refund = {
+				id: refundId,
+				paymentIntentId: intent.id,
+				providerRefundId: params.providerRefundId,
+				amount: refundAmount,
+				reason: params.reason,
+				status: "succeeded",
+				createdAt: now,
+				updatedAt: now,
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("refund", refundId, refund as Record<string, any>);
+
+			const updatedIntent: PaymentIntent = {
+				...intent,
+				status: "refunded",
+				updatedAt: now,
+			};
+			await data.upsert(
+				"paymentIntent",
+				intent.id,
+				// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+				updatedIntent as unknown as Record<string, any>,
+			);
+
+			return { intent: updatedIntent, refund };
+		},
+	};
+}

package/src/service.ts

@@ -0,0 +1,160 @@
+import type { ModuleController } from "@86d-app/core";
+
+export type PaymentIntentStatus =
+	| "pending"
+	| "processing"
+	| "succeeded"
+	| "failed"
+	| "cancelled"
+	| "refunded";
+
+export type RefundStatus = "pending" | "succeeded" | "failed";
+
+export interface PaymentIntent {
+	id: string;
+	providerIntentId?: string | undefined;
+	customerId?: string | undefined;
+	email?: string | undefined;
+	amount: number;
+	currency: string;
+	status: PaymentIntentStatus;
+	paymentMethodId?: string | undefined;
+	orderId?: string | undefined;
+	checkoutSessionId?: string | undefined;
+	metadata: Record<string, unknown>;
+	providerMetadata: Record<string, unknown>;
+	createdAt: Date;
+	updatedAt: Date;
+}
+
+export interface PaymentMethod {
+	id: string;
+	customerId: string;
+	providerMethodId: string;
+	type: string;
+	last4?: string | undefined;
+	brand?: string | undefined;
+	expiryMonth?: number | undefined;
+	expiryYear?: number | undefined;
+	isDefault: boolean;
+	createdAt: Date;
+	updatedAt: Date;
+}
+
+export interface Refund {
+	id: string;
+	paymentIntentId: string;
+	providerRefundId: string;
+	amount: number;
+	reason?: string | undefined;
+	status: RefundStatus;
+	createdAt: Date;
+	updatedAt: Date;
+}
+
+// ── Provider interface ────────────────────────────────────────────────────────
+
+export interface ProviderIntentResult {
+	providerIntentId: string;
+	status: "pending" | "processing" | "succeeded" | "failed" | "cancelled";
+	providerMetadata?: Record<string, unknown> | undefined;
+}
+
+export interface ProviderRefundResult {
+	providerRefundId: string;
+	status: "pending" | "succeeded" | "failed";
+	providerMetadata?: Record<string, unknown> | undefined;
+}
+
+/** Implement this interface to connect a payment processor (e.g. Stripe). */
+export interface PaymentProvider {
+	createIntent(params: {
+		amount: number;
+		currency: string;
+		metadata?: Record<string, unknown> | undefined;
+	}): Promise<ProviderIntentResult>;
+
+	confirmIntent(providerIntentId: string): Promise<ProviderIntentResult>;
+
+	cancelIntent(providerIntentId: string): Promise<ProviderIntentResult>;
+
+	createRefund(params: {
+		providerIntentId: string;
+		amount?: number | undefined;
+		reason?: string | undefined;
+	}): Promise<ProviderRefundResult>;
+}
+
+// ── Controller interface ──────────────────────────────────────────────────────
+
+export interface PaymentController extends ModuleController {
+	// ── Intents ───────────────────────────────────────────────────────────
+	createIntent(params: {
+		amount: number;
+		currency?: string | undefined;
+		customerId?: string | undefined;
+		email?: string | undefined;
+		orderId?: string | undefined;
+		checkoutSessionId?: string | undefined;
+		metadata?: Record<string, unknown> | undefined;
+	}): Promise<PaymentIntent>;
+
+	getIntent(id: string): Promise<PaymentIntent | null>;
+
+	confirmIntent(id: string): Promise<PaymentIntent | null>;
+
+	cancelIntent(id: string): Promise<PaymentIntent | null>;
+
+	listIntents(params?: {
+		customerId?: string | undefined;
+		status?: PaymentIntentStatus | undefined;
+		orderId?: string | undefined;
+		take?: number | undefined;
+		skip?: number | undefined;
+	}): Promise<PaymentIntent[]>;
+
+	// ── Payment methods ───────────────────────────────────────────────────
+	savePaymentMethod(params: {
+		customerId: string;
+		providerMethodId: string;
+		type?: string | undefined;
+		last4?: string | undefined;
+		brand?: string | undefined;
+		expiryMonth?: number | undefined;
+		expiryYear?: number | undefined;
+		isDefault?: boolean | undefined;
+	}): Promise<PaymentMethod>;
+
+	getPaymentMethod(id: string): Promise<PaymentMethod | null>;
+
+	listPaymentMethods(customerId: string): Promise<PaymentMethod[]>;
+
+	deletePaymentMethod(id: string): Promise<boolean>;
+
+	// ── Refunds ───────────────────────────────────────────────────────────
+	createRefund(params: {
+		intentId: string;
+		amount?: number | undefined;
+		reason?: string | undefined;
+	}): Promise<Refund>;
+
+	getRefund(id: string): Promise<Refund | null>;
+
+	listRefunds(intentId: string): Promise<Refund[]>;
+
+	// ── Webhook handling ──────────────────────────────────────────────────
+	/** Look up a payment intent by its provider-assigned ID and update its status. */
+	handleWebhookEvent(params: {
+		providerIntentId: string;
+		status: PaymentIntentStatus;
+		providerMetadata?: Record<string, unknown> | undefined;
+	}): Promise<PaymentIntent | null>;
+
+	/** Look up a payment intent by its provider-assigned ID and record a refund. */
+	handleWebhookRefund(params: {
+		providerIntentId: string;
+		providerRefundId: string;
+		amount?: number | undefined;
+		reason?: string | undefined;
+	}): Promise<{ intent: PaymentIntent; refund: Refund } | null>;
+}

package/src/store/endpoints/cancel-intent.ts

@@ -0,0 +1,16 @@
+import { createStoreEndpoint, z } from "@86d-app/core";
+import type { PaymentController } from "../../service";
+
+export const cancelIntent = createStoreEndpoint(
+	"/payments/intents/:id/cancel",
+	{
+		method: "POST",
+		params: z.object({ id: z.string() }),
+	},
+	async (ctx) => {
+		const controller = ctx.context.controllers.payments as PaymentController;
+		const intent = await controller.cancelIntent(ctx.params.id);
+		if (!intent) return { error: "Payment intent not found", status: 404 };
+		return { intent };
+	},
+);

package/src/store/endpoints/confirm-intent.ts

@@ -0,0 +1,16 @@
+import { createStoreEndpoint, z } from "@86d-app/core";
+import type { PaymentController } from "../../service";
+
+export const confirmIntent = createStoreEndpoint(
+	"/payments/intents/:id/confirm",
+	{
+		method: "POST",
+		params: z.object({ id: z.string() }),
+	},
+	async (ctx) => {
+		const controller = ctx.context.controllers.payments as PaymentController;
+		const intent = await controller.confirmIntent(ctx.params.id);
+		if (!intent) return { error: "Payment intent not found", status: 404 };
+		return { intent };
+	},
+);

package/src/store/endpoints/create-intent.ts

@@ -0,0 +1,29 @@
+import { createStoreEndpoint, z } from "@86d-app/core";
+import type { PaymentController } from "../../service";
+
+export const createIntent = createStoreEndpoint(
+	"/payments/intents",
+	{
+		method: "POST",
+		body: z.object({
+			amount: z.number().int().positive(),
+			currency: z.string().max(3).optional(),
+			email: z.string().email().optional(),
+			orderId: z.string().optional(),
+			checkoutSessionId: z.string().optional(),
+			metadata: z.record(z.string(), z.unknown()).optional(),
+		}),
+	},
+	async (ctx) => {
+		const controller = ctx.context.controllers.payments as PaymentController;
+		const intent = await controller.createIntent({
+			amount: ctx.body.amount,
+			currency: ctx.body.currency,
+			email: ctx.body.email,
+			orderId: ctx.body.orderId,
+			checkoutSessionId: ctx.body.checkoutSessionId,
+			metadata: ctx.body.metadata,
+		});
+		return { intent };
+	},
+);

package/src/store/endpoints/delete-method.ts

@@ -0,0 +1,17 @@
+import { createStoreEndpoint, z } from "@86d-app/core";
+import type { PaymentController } from "../../service";
+
+export const deletePaymentMethod = createStoreEndpoint(
+	"/payments/methods/:id",
+	{
+		method: "DELETE",
+		params: z.object({ id: z.string() }),
+	},
+	async (ctx) => {
+		const controller = ctx.context.controllers.payments as PaymentController;
+		const method = await controller.getPaymentMethod(ctx.params.id);
+		if (!method) return { error: "Payment method not found", status: 404 };
+		const deleted = await controller.deletePaymentMethod(ctx.params.id);
+		return { deleted };
+	},
+);

package/src/store/endpoints/get-intent.ts

@@ -0,0 +1,16 @@
+import { createStoreEndpoint, z } from "@86d-app/core";
+import type { PaymentController } from "../../service";
+
+export const getIntent = createStoreEndpoint(
+	"/payments/intents/:id",
+	{
+		method: "GET",
+		params: z.object({ id: z.string() }),
+	},
+	async (ctx) => {
+		const controller = ctx.context.controllers.payments as PaymentController;
+		const intent = await controller.getIntent(ctx.params.id);
+		if (!intent) return { error: "Payment intent not found", status: 404 };
+		return { intent };
+	},
+);

package/src/store/endpoints/index.ts

@@ -0,0 +1,15 @@
+import { cancelIntent } from "./cancel-intent";
+import { confirmIntent } from "./confirm-intent";
+import { createIntent } from "./create-intent";
+import { deletePaymentMethod } from "./delete-method";
+import { getIntent } from "./get-intent";
+import { listPaymentMethods } from "./list-methods";
+
+export const storeEndpoints = {
+	"/payments/intents": createIntent,
+	"/payments/intents/:id": getIntent,
+	"/payments/intents/:id/confirm": confirmIntent,
+	"/payments/intents/:id/cancel": cancelIntent,
+	"/payments/methods": listPaymentMethods,
+	"/payments/methods/:id": deletePaymentMethod,
+};