better-supabase 0.7.1 → 0.9.0

package/dist/blocks/orders/index.js

@@ -0,0 +1,589 @@
+import { n as dbError } from "../../errors-8i6tSICm.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-BlgnMB0H.js";
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { D as recordOf, I as textOf, d as enumOrThrow, n as applyTemporal, o as blockCall, y as nullableText } from "../../block-helpers-CfG_MvDR.js";
+import { i as wrapTransport, n as extendBlock, r as withBlockHooks } from "../../block-hooks-BsXncUlZ.js";
+import { n as blockFields, o as readFields } from "../../block-fields-ffD6Gxe4.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { r as defineMetric } from "../../metric-definition-BjxVn4R5.js";
+import { d as money } from "../../money-95Rff2vT.js";
+import { n as paymentProviderOf } from "../../payments-h45bswA-.js";
+import { a as taxProviderOf } from "../../tax-D_kSCdWU.js";
+import { i as moneyOf, t as amountText } from "../../money-codec-C_-K5ZUU.js";
+import { a as RETURN_STATUSES, c as quoteToJson, d as transactionToJson, i as REFUND_STATUSES, l as refundedTaxLines, n as ORDER_STATUSES, o as orderOf, s as pricedCartOf, t as FULFILLMENT_STATUSES, u as shippingOptionsOf } from "../../codecs-YAekuQ08.js";
+import { t as ordersSqlOptions } from "../../options-QKP9FFcK.js";
+//#region src/blocks/orders/metrics.ts
+/**
+* Metric definitions over the orders table: orders placed, and revenue and
+* average order value from paid orders, in minor units of `currency`. Pass
+* them to `blocks.metrics.options.metrics` and `createMetrics`.
+*/
+function orderMetrics(options) {
+	const shared = {
+		table: `${options.schema ?? "better_supabase"}.orders`,
+		tenant: "tenant_id",
+		...options.tz === void 0 ? {} : { tz: options.tz }
+	};
+	const paid = {
+		...shared,
+		timeColumn: "paid_at",
+		where: { currency: options.currency },
+		unit: options.currency
+	};
+	return [
+		defineMetric({
+			key: "orders",
+			label: "Orders",
+			measure: "count",
+			timeColumn: "placed_at",
+			...shared
+		}),
+		defineMetric({
+			key: "revenue",
+			label: "Revenue",
+			measure: { sum: "total" },
+			...paid
+		}),
+		defineMetric({
+			key: "average_order_value",
+			label: "Average order value",
+			measure: { avg: "total" },
+			...paid
+		})
+	];
+}
+/** The events that add rows to `orderMetrics`, for `metricsSink` or `createBlocks({ metricEvents })`. */
+const ORDER_METRIC_EVENTS = {
+	"order.placed": ["orders"],
+	"order.paid": ["revenue", "average_order_value"]
+};
+//#endregion
+//#region src/blocks/orders/orders.ts
+const isTrue = (value) => value === true;
+const failure = (hint, message) => dbError("invalid_request", message, { hint });
+function maxRowsOf(payload) {
+	if (!isRecord(payload)) return;
+	const value = payload["maxRows"];
+	return typeof value === "number" ? value : void 0;
+}
+function paymentRecordOf(value, currency) {
+	const row = recordOf(value, "record_payment");
+	return {
+		orderId: textOf(row["orderId"]),
+		status: enumOrThrow(row["status"], ORDER_STATUSES, "order status"),
+		paidTotal: moneyOf(row["paidTotal"], currency),
+		newlyPaid: row["newlyPaid"] === true,
+		invoiceNumber: nullableText(row["invoiceNumber"])
+	};
+}
+const PAYMENT_EVENT_STATUS = {
+	"payment.requires_action": "requires_action",
+	"payment.processing": "processing",
+	"payment.authorized": "authorized",
+	"payment.succeeded": "succeeded",
+	"payment.failed": "failed",
+	"payment.canceled": "canceled"
+};
+function refundStatusOf(status) {
+	return status === "canceled" ? "failed" : status;
+}
+/** Carts, checkout, payments, fulfillments, returns, refunds and invoices over the `orders` SQL module. */
+function createOrders(options) {
+	applyTemporal(options);
+	const fields = blockFields(options.fields, "order fields");
+	const parsed = (result) => result.andThen((order) => readFields(fields, order));
+	const payments = options.payments ? paymentProviderOf(options.payments) : void 0;
+	const tax = options.tax ? taxProviderOf(options.tax) : void 0;
+	const logger = options.logger ?? console;
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const service = blockCall(options.service ?? options.transport, options.schema, options.mappers);
+	const categoryOf = (line) => typeof options.taxCategory === "function" ? options.taxCategory(line) : options.taxCategory;
+	const loadOrder = (orderId) => parsed(service("get_order", { order_id: orderId }, orderOf));
+	const recordPayment = (orderId, payment) => service("record_payment", {
+		order_id: orderId,
+		provider: payment.provider,
+		reference: payment.id,
+		status: payment.status,
+		currency: payment.amount.currency,
+		amount: amountText(payment.amount),
+		captured: amountText(payment.captured),
+		refunded: amountText(payment.refunded)
+	}, (value) => paymentRecordOf(value, payment.amount.currency));
+	const commitTax = (orderId) => AsyncResult.from(async () => {
+		if (!tax) return ok(null);
+		const order = await loadOrder(orderId);
+		if (!order.ok) return order;
+		const { taxQuote, taxTransaction } = order.data;
+		if (taxTransaction) return ok(taxTransaction);
+		if (!taxQuote || order.data.invoiceNumber === null) return ok(null);
+		const committed = await tax.commit({
+			quote: taxQuote,
+			reference: order.data.number
+		}, { idempotencyKey: `tax:${orderId}` });
+		if (!committed.ok) return committed;
+		const stored = await service("set_order_tax_transaction", {
+			order_id: orderId,
+			tax_transaction: transactionToJson(committed.data)
+		}, isTrue);
+		return stored.ok ? ok(committed.data) : stored;
+	});
+	/** Commits the tax once a payment paid the order; a failure is logged and retried with `commitTax`. */
+	const afterPayment = async (record) => {
+		if (!record.newlyPaid) return;
+		const committed = await commitTax(record.orderId);
+		if (!committed.ok) logger.warn("orders: tax commit failed; retry with commitTax", {
+			orderId: record.orderId,
+			error: committed.error
+		});
+	};
+	const record = (orderId, payment) => recordPayment(orderId, payment).andThen(async (result) => {
+		await afterPayment(result);
+		return ok(result);
+	});
+	const taxCartOf = (cart, address) => {
+		const inclusive = options.pricesIncludeTax === true;
+		return {
+			currency: cart.currency,
+			lines: cart.lines.map((line) => {
+				const category = categoryOf(line);
+				return {
+					id: line.id,
+					amount: line.total,
+					quantity: line.quantity,
+					...category === void 0 ? {} : { taxCategory: category },
+					...inclusive ? { inclusive } : {}
+				};
+			}),
+			...cart.shippingTotal.amount > 0n ? { shipping: {
+				amount: cart.shippingTotal,
+				...options.shippingTaxCategory === void 0 ? {} : { taxCategory: options.shippingTaxCategory },
+				...inclusive ? { inclusive } : {}
+			} } : {},
+			address: {
+				country: address.country,
+				...address.state === void 0 ? {} : { state: address.state },
+				...address.postalCode === void 0 ? {} : { postalCode: address.postalCode },
+				...address.city === void 0 ? {} : { city: address.city },
+				...address.line1 === void 0 ? {} : { line1: address.line1 },
+				...address.line2 === void 0 ? {} : { line2: address.line2 }
+			},
+			reference: cart.id
+		};
+	};
+	const checkout = (cartId, input = {}) => AsyncResult.from(async () => {
+		const checked = input.fields === void 0 ? ok(void 0) : await fields.write({ ...input.fields });
+		if (!checked.ok) return checked;
+		const priced = await call("price_cart", { cart: cartId }, pricedCartOf);
+		if (!priced.ok) return priced;
+		const cart = priced.data;
+		if (cart.status === "open") {
+			if (cart.lines.length === 0) return err(failure("ORDERS_CART_EMPTY", "the cart has no lines"));
+			if (cart.problems.length > 0) return err(failure("ORDERS_CART_INVALID", `the cart can't check out: ${cart.problems.map((problem) => problem.problem).join(", ")}`));
+		}
+		let quote = null;
+		if (tax && cart.status === "open") {
+			const address = cart.shippingAddress ?? cart.billingAddress;
+			if (!address) return err(failure("ORDERS_ADDRESS_REQUIRED", "tax needs a shipping or billing address on the cart"));
+			const quoted = await tax.quote(taxCartOf(cart, address));
+			if (!quoted.ok) return quoted;
+			quote = quoteToJson(quoted.data);
+		}
+		const placed = await parsed(service("place_order", {
+			cart: cartId,
+			tax: quote,
+			expected_total: amountText(cart.total),
+			location: input.locationId ?? null,
+			fields: checked.data
+		}, orderOf));
+		if (!placed.ok) return placed;
+		const order = placed.data;
+		if (order.status !== "pending_payment") return ok({
+			order,
+			payment: null
+		});
+		if (order.total.amount === 0n) {
+			const zero = money(0, order.currency);
+			const free = await record(order.id, {
+				id: `free:${order.id}`,
+				provider: "none",
+				status: "succeeded",
+				amount: zero,
+				captured: zero,
+				refunded: zero,
+				reference: order.id,
+				metadata: {}
+			});
+			if (!free.ok) return free;
+			const paid = await loadOrder(order.id);
+			return paid.ok ? ok({
+				order: paid.data,
+				payment: null
+			}) : paid;
+		}
+		if (!payments) return ok({
+			order,
+			payment: null
+		});
+		const created = await payments.createPayment({
+			amount: order.total,
+			reference: order.id,
+			capture: options.capture ?? "automatic",
+			...input.customer === void 0 ? {} : { customer: input.customer },
+			description: `Order ${order.number}`,
+			...input.returnUrl === void 0 ? {} : { returnUrl: input.returnUrl },
+			metadata: {
+				...input.metadata,
+				orderId: order.id,
+				orderNumber: order.number
+			}
+		}, { idempotencyKey: `order:${order.id}:payment` });
+		if (!created.ok) return created;
+		const stored = await record(order.id, created.data);
+		if (!stored.ok) return stored;
+		const current = await loadOrder(order.id);
+		return current.ok ? ok({
+			order: current.data,
+			payment: created.data
+		}) : current;
+	});
+	const capture = (orderId) => AsyncResult.from(async () => {
+		if (!payments) return err(failure("ORDERS_NO_PAYMENTS", "capture needs a payments provider"));
+		const order = await loadOrder(orderId);
+		if (!order.ok) return order;
+		for (const payment of order.data.payments) {
+			if (payment.status !== "authorized" || payment.provider !== payments.name) continue;
+			const captured = await payments.capture(payment.reference, {}, { idempotencyKey: `capture:${payment.id}` });
+			if (!captured.ok) return captured;
+			const stored = await record(orderId, captured.data);
+			if (!stored.ok) return stored;
+		}
+		return loadOrder(orderId);
+	});
+	const completeRefund = (refundId, status, providerReference) => service("complete_refund", {
+		refund: refundId,
+		status,
+		provider_reference: providerReference
+	}, (value) => recordOf(value, "complete_refund")).andThen(async (row) => {
+		const order = await loadOrder(textOf(row["orderId"]));
+		if (!order.ok) return order;
+		const { currency } = order.data;
+		return ok({
+			id: textOf(row["id"]),
+			orderId: order.data.id,
+			amount: moneyOf(row["amount"], currency),
+			status: enumOrThrow(row["status"], REFUND_STATUSES, "refund status"),
+			orderStatus: enumOrThrow(row["orderStatus"], ORDER_STATUSES, "order status"),
+			refundedTotal: moneyOf(row["refundedTotal"], currency)
+		});
+	});
+	const reverseTax = async (outcome) => {
+		if (!tax || outcome.status !== "succeeded") return {
+			...outcome,
+			taxReversal: null
+		};
+		const order = await loadOrder(outcome.orderId);
+		const transaction = order.ok ? order.data.taxTransaction : void 0;
+		if (!order.ok || !transaction) return {
+			...outcome,
+			taxReversal: null
+		};
+		const whole = outcome.amount.amount >= order.data.total.amount;
+		const reversed = await tax.reverse({
+			transaction,
+			reference: outcome.id,
+			...whole ? {} : { lines: refundedTaxLines(transaction, outcome.amount, order.data.total) }
+		}, { idempotencyKey: `tax-reverse:${outcome.id}` });
+		if (reversed.ok) return {
+			...outcome,
+			taxReversal: reversed.data
+		};
+		logger.warn("orders: tax reversal failed", {
+			refundId: outcome.id,
+			error: reversed.error
+		});
+		return {
+			...outcome,
+			taxReversal: null
+		};
+	};
+	const refund = (orderId, input = {}) => AsyncResult.from(async () => {
+		if (!payments) return err(failure("ORDERS_NO_PAYMENTS", "refunds need a payments provider"));
+		const created = await call("create_refund", {
+			order_id: orderId,
+			amount: input.amount === void 0 ? null : amountText(input.amount),
+			return_id: input.returnId ?? null,
+			reason: input.reason ?? null
+		}, (value) => recordOf(value, "create_refund"));
+		if (!created.ok) return created;
+		const row = created.data;
+		const refundId = textOf(row["id"]);
+		const amount = moneyOf(row["amount"], textOf(row["currency"]));
+		const providerRefund = await payments.refund(textOf(row["paymentReference"]), {
+			amount,
+			...input.reason === void 0 ? {} : { reason: input.reason }
+		}, { idempotencyKey: `refund:${refundId}` });
+		if (!providerRefund.ok) {
+			await completeRefund(refundId, "failed", null);
+			return providerRefund;
+		}
+		const completed = await completeRefund(refundId, refundStatusOf(providerRefund.data.status), providerRefund.data.id);
+		if (!completed.ok) return completed;
+		return ok(await reverseTax(completed.data));
+	});
+	const handlePaymentEvent = (event) => AsyncResult.from(async () => {
+		if (event.type === "refund.succeeded" || event.type === "refund.failed") {
+			if (event.refundId === void 0) return ok({
+				event: event.id,
+				kind: "ignored",
+				reason: "no refund id"
+			});
+			const completed = await completeRefund(null, event.type === "refund.succeeded" ? "succeeded" : "failed", event.refundId);
+			if (!completed.ok) {
+				if (completed.error.hint === "ORDERS_REFUND_NOT_FOUND") return ok({
+					event: event.id,
+					kind: "ignored",
+					reason: "unknown refund"
+				});
+				return completed;
+			}
+			return ok({
+				event: event.id,
+				kind: "refund",
+				refund: await reverseTax(completed.data)
+			});
+		}
+		let payment;
+		if (payments?.get) {
+			const fetched = await payments.get(event.paymentId);
+			if (!fetched.ok) return fetched;
+			payment = fetched.data;
+		} else {
+			if (event.amount === void 0) return ok({
+				event: event.id,
+				kind: "ignored",
+				reason: "no amount"
+			});
+			const status = PAYMENT_EVENT_STATUS[event.type];
+			const zero = money(0, event.amount.currency);
+			payment = {
+				id: event.paymentId,
+				provider: payments?.name ?? "unknown",
+				status,
+				amount: event.amount,
+				captured: status === "succeeded" ? event.amount : zero,
+				refunded: zero,
+				reference: event.reference ?? "",
+				metadata: {}
+			};
+		}
+		const orderId = payment.reference === "" ? event.reference ?? null : payment.reference;
+		const stored = await record(orderId, payment);
+		if (!stored.ok) {
+			if (stored.error.hint === "ORDERS_ORDER_NOT_FOUND") return ok({
+				event: event.id,
+				kind: "ignored",
+				reason: "unknown order"
+			});
+			return stored;
+		}
+		return ok({
+			event: event.id,
+			kind: "payment",
+			record: stored.data
+		});
+	});
+	const webhook = (input) => AsyncResult.from(async () => {
+		if (!payments) return err(failure("ORDERS_NO_PAYMENTS", "webhooks need a payments provider"));
+		const parsed = await payments.parseWebhook(input);
+		if (!parsed.ok) return parsed;
+		const outcomes = [];
+		for (const event of parsed.data) {
+			const outcome = await handlePaymentEvent(event);
+			if (!outcome.ok) return outcome;
+			outcomes.push(outcome.data);
+		}
+		return ok(outcomes);
+	});
+	const cancelOrder = (orderId, reason) => call("cancel_order", {
+		order_id: orderId,
+		reason: reason ?? null
+	}, isTrue).andThen(async (cancelled) => {
+		if (!cancelled || !payments?.cancel) return ok(cancelled);
+		const order = await loadOrder(orderId);
+		if (!order.ok) return ok(cancelled);
+		for (const payment of order.data.payments) {
+			if (payment.provider !== payments.name || ![
+				"requires_action",
+				"processing",
+				"authorized"
+			].includes(payment.status)) continue;
+			const released = await payments.cancel(payment.reference, { idempotencyKey: `cancel:${payment.id}` });
+			if (released.ok) await recordPayment(orderId, released.data);
+			else logger.warn("orders: cancelling the payment failed", {
+				orderId,
+				paymentId: payment.reference,
+				error: released.error
+			});
+		}
+		return ok(cancelled);
+	});
+	const expireOrders = (maxRows) => service("expire_orders", { max_rows: maxRows ?? null }, Number);
+	return withBlockHooks({
+		saveShippingRate: (organizationId, input) => call("save_shipping_rate", {
+			tenant: organizationId,
+			rate: input.id ?? null,
+			data: {
+				name: input.name,
+				countries: input.countries ?? [],
+				kind: input.kind ?? "flat",
+				currency: input.amount.currency,
+				amount: amountText(input.amount),
+				...input.amountPerKg === void 0 ? {} : { amountPerKg: amountText(input.amountPerKg) },
+				...input.freeOver === void 0 ? {} : { freeOver: amountText(input.freeOver) },
+				active: input.active ?? true
+			}
+		}, (value) => ({ id: textOf(recordOf(value, "save_shipping_rate")["id"]) })),
+		deleteShippingRate: (rateId) => call("delete_shipping_rate", { rate: rateId }, isTrue),
+		createCart: (organizationId, input) => call("create_cart", {
+			tenant: organizationId,
+			currency: input.currency,
+			price_list: input.priceListId ?? null,
+			email: input.email ?? null
+		}, (value) => {
+			const row = recordOf(value, "create_cart");
+			return {
+				id: textOf(row["id"]),
+				currency: textOf(row["currency"])
+			};
+		}),
+		addToCart: (cartId, variantId, quantity) => call("add_to_cart", {
+			cart: cartId,
+			variant: variantId,
+			quantity
+		}, (value) => {
+			const row = recordOf(value, "add_to_cart");
+			return {
+				lineId: textOf(row["lineId"]),
+				quantity: Number(row["quantity"])
+			};
+		}),
+		setCartLine: (cartId, variantId, quantity) => call("set_cart_line", {
+			cart: cartId,
+			variant: variantId,
+			quantity
+		}, (value) => {
+			const row = recordOf(value, "set_cart_line");
+			return {
+				lineId: nullableText(row["lineId"]),
+				quantity: Number(row["quantity"])
+			};
+		}),
+		setCartDetails: (cartId, details) => call("set_cart_details", {
+			cart: cartId,
+			email: details.email ?? null,
+			shipping_address: details.shippingAddress ?? null,
+			billing_address: details.billingAddress ?? null
+		}, isTrue),
+		setShippingRate: (cartId, rateId) => call("set_cart_shipping_rate", {
+			cart: cartId,
+			rate: rateId
+		}, isTrue),
+		shippingOptions: (cartId) => call("shipping_options", { cart: cartId }, shippingOptionsOf),
+		priceCart: (cartId) => call("price_cart", { cart: cartId }, pricedCartOf),
+		mergeCarts: (fromUserId, toUserId) => service("merge_carts", {
+			from_user: fromUserId,
+			to_user: toUserId
+		}, Number),
+		checkout,
+		recordPayment,
+		capture,
+		handlePaymentEvent,
+		webhook,
+		commitTax,
+		cancelOrder,
+		expireOrders,
+		getOrder: (orderId) => parsed(call("get_order", { order_id: orderId }, orderOf)),
+		createFulfillment: (orderId, input = {}) => call("create_fulfillment", {
+			order_id: orderId,
+			lines: input.lines ? input.lines.map((line) => ({
+				lineId: line.lineId,
+				quantity: line.quantity
+			})) : null,
+			location: input.locationId ?? null,
+			carrier: input.carrier ?? null,
+			tracking_number: input.trackingNumber ?? null,
+			tracking_url: input.trackingUrl ?? null
+		}, (value) => ({ id: textOf(recordOf(value, "create_fulfillment")["id"]) })),
+		shipFulfillment: (fulfillmentId, tracking = {}) => call("ship_fulfillment", {
+			fulfillment: fulfillmentId,
+			carrier: tracking.carrier ?? null,
+			tracking_number: tracking.trackingNumber ?? null,
+			tracking_url: tracking.trackingUrl ?? null
+		}, isTrue),
+		deliverFulfillment: (fulfillmentId) => call("deliver_fulfillment", { fulfillment: fulfillmentId }, isTrue),
+		cancelFulfillment: (fulfillmentId) => call("cancel_fulfillment", { fulfillment: fulfillmentId }, isTrue),
+		requestReturn: (orderId, lines, reason) => call("request_return", {
+			order_id: orderId,
+			lines: lines.map((line) => ({
+				lineId: line.lineId,
+				quantity: line.quantity
+			})),
+			reason: reason ?? null
+		}, (value) => {
+			const row = recordOf(value, "request_return");
+			return {
+				id: textOf(row["id"]),
+				quantity: Number(row["quantity"])
+			};
+		}),
+		receiveReturn: (returnId, receive = {}) => call("receive_return", {
+			return_id: returnId,
+			restock: receive.restock ?? true,
+			location: receive.locationId ?? null
+		}, isTrue),
+		rejectReturn: (returnId) => call("reject_return", { return_id: returnId }, isTrue),
+		refund,
+		invoice: (orderId) => parsed(call("get_order", { order_id: orderId }, orderOf)).andThen((order) => Promise.resolve(order.invoiceNumber === null || order.invoicedAt === void 0 ? err(failure("ORDERS_NOT_INVOICED", "the order isn't paid yet")) : ok({
+			number: order.invoiceNumber,
+			issuedAt: order.invoicedAt,
+			order
+		}))),
+		job: async (payload) => {
+			await expireOrders(maxRowsOf(payload)).orThrow();
+		}
+	}, options.hooks, {
+		block: "orders",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/orders/events.ts
+/** The `orders` block's event types, for its manifest and `onBlockEvent`. */
+const ordersEvents = defineEvents({
+	"order.placed": event(),
+	"order.paid": event(),
+	"order.cancelled": event(),
+	"order.fulfilled": event(),
+	"order.completed": event(),
+	"order.refunded": event(),
+	"fulfillment.shipped": event(),
+	"fulfillment.delivered": event(),
+	"return.requested": event(),
+	"return.received": event()
+});
+//#endregion
+//#region src/blocks/orders/manifest.ts
+/** The `orders` block's manifest (ADR 0029). */
+const ordersBlock = defineBlock({
+	name: "orders",
+	sql: ["orders"],
+	options: { orders: ordersSqlOptions },
+	events: ordersEvents,
+	create: createOrders,
+	category: "commerce",
+	recipes: ["order-detail"]
+});
+//#endregion
+export { FULFILLMENT_STATUSES, ORDER_METRIC_EVENTS, ORDER_STATUSES, REFUND_STATUSES, RETURN_STATUSES, createOrders, dbTransport, extendBlock, orderMetrics, ordersBlock, ordersEvents, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };