Allow shipping-free Tabby checkouts (#15)

Author: y0u-0

.changeset/soft-courses-float.md

@@ -0,0 +1,5 @@
+---
+"better-auth-bnpl": patch
+---
+
+Allow digital-only Tabby checkouts and order history to omit shipping addresses while retaining Tamara's shipping requirement.

src/__tests__/checkout.test.ts

@@ -166,6 +166,16 @@ describe("checkout session contract (authenticatedUsersOnly)", () => {
 		const res = await postCheckout(auth, baseURL, cookie, checkoutBody());
 		expect(res.status).toBe(200);
 	});
+	it("permits checkout without a shipping address", async () => {
+		const { auth, baseURL, captured } = makeHarness();
+		const cookie = await signUp(auth, baseURL);
+		const { shippingAddress: _shippingAddress, ...body } = checkoutBody();
+
+		const res = await postCheckout(auth, baseURL, cookie, body);
+
+		expect(res.status).toBe(200);
+		expect(captured.canonical?.shippingAddress).toBeUndefined();
+	});
 });
 describe("notification URL basepath", () => {
 	it("builds the webhook URL under a non-default basePath", async () => {

src/__tests__/providers/tabby/adapter.test.ts

@@ -82,6 +82,8 @@ const checkoutProviderData = {
 } satisfies TabbyCheckoutData;
 const checkoutHistoryOrder = checkoutProviderData.order_history[0];
 if (!checkoutHistoryOrder) throw new Error("checkout history fixture is missing");
+const checkoutShippingAddress = baseCheckout.shippingAddress;
+if (!checkoutShippingAddress) throw new Error("checkout shipping fixture is missing");
 describe("toTabbyBuyer", () => {
 	it("preserves a provided buyer name after trimming", () => {
 		expect(
@@ -117,8 +119,10 @@ describe("toTabbyCheckoutRequest", () => {
 		expect(req.payment.amount).toBe("500.00");
 		expect(req.payment.currency).toBe("AED");
 		expect(req.payment.buyer.name).toBe("Ali Dhamen");
-		expect(req.payment.shipping_address.address).toBe("Sheikh Zayed Rd");
-		expect(req.payment.shipping_address.city).toBe("Dubai");
+		expect(req.payment.shipping_address).toMatchObject({
+			address: "Sheikh Zayed Rd",
+			city: "Dubai",
+		});
 		expect(req.payment.order.reference_id).toBe("ord-1");
 		expect(req.payment.order.items[0]?.title).toBe("Keyboard");
 		expect(req.payment.order.items[0]?.unit_price).toBe("500.00");
@@ -141,11 +145,11 @@ describe("toTabbyCheckoutRequest", () => {
 		const req = toTabbyCheckoutRequest(
 			{
 				...baseCheckout,
-				shippingAddress: { ...baseCheckout.shippingAddress, line2: "Floor 5" },
+				shippingAddress: { ...checkoutShippingAddress, line2: "Floor 5" },
 			},
 			{ merchantCode: "M" },
 		);
-		expect(req.payment.shipping_address.address).toBe("Sheikh Zayed Rd, Floor 5");
+		expect(req.payment.shipping_address?.address).toBe("Sheikh Zayed Rd, Floor 5");
 	});
 	it("validates and maps trusted checkout provider data to Tabby's payment fields", () => {
 		const req = toTabbyCheckoutRequest(
@@ -165,6 +169,23 @@ describe("toTabbyCheckoutRequest", () => {
 			content_type: "application/vnd.tabby.v1+json",
 		});
 	});
+	it("accepts order history without shipping_address and omits the key", () => {
+		const { shipping_address: _shippingAddress, ...historyWithoutShipping } = checkoutHistoryOrder;
+		const { shippingAddress: _checkoutShippingAddress, ...checkoutWithoutShipping } = baseCheckout;
+		const req = toTabbyCheckoutRequest(
+			{
+				...checkoutWithoutShipping,
+				providerData: {
+					...checkoutProviderData,
+					order_history: [historyWithoutShipping],
+				},
+			},
+			{ merchantCode: "M" },
+		);
+
+		expect(req.payment.order_history?.[0]).not.toHaveProperty("shipping_address");
+		expect(JSON.stringify(req)).not.toContain('"shipping_address"');
+	});
 	it("preserves the previous payment shape when checkout provider data is absent", () => {
 		const req = toTabbyCheckoutRequest(baseCheckout, { merchantCode: "M" });
 		expect(req.payment).not.toHaveProperty("buyer_history");

src/__tests__/providers/tabby/factory.test.ts

@@ -384,6 +384,37 @@ describe("tabby() factory", () => {
 			expect(result.checkoutUrl).toBe("https://tabby/pay-later");
 			expect(result.providerOrderId).toBe("payment-1");
 		});
+		it("omits shipping_address from the outgoing JSON when shipping is absent", async () => {
+			let requestBody: unknown;
+			const fetch: typeof globalThis.fetch = async (_input, init) => {
+				requestBody = parseRequestBody(init?.body);
+				return new Response(
+					JSON.stringify({
+						id: "checkout-digital",
+						status: "created",
+						configuration: {
+							available_products: {
+								installments: [{ web_url: "https://tabby/digital" }],
+							},
+						},
+						payment: {
+							id: "payment-digital",
+							status: "CREATED",
+							amount: "100.00",
+							currency: "SAR",
+						},
+					}),
+					{ status: 200, headers: { "content-type": "application/json" } },
+				);
+			};
+			const provider = tabby({ ...baseConfig, fetch });
+			const { shippingAddress: _shippingAddress, ...input } = checkoutInput;
+
+			await provider.createCheckout(input, ctx);
+
+			const parsed = z.object({ payment: z.object({}).passthrough() }).parse(requestBody);
+			expect(parsed.payment).not.toHaveProperty("shipping_address");
+		});
 	});
 	describe("capture/refund references", () => {
 		it("requires operation references before calling Tabby", async () => {

src/__tests__/providers/tamara/adapter.test.ts

@@ -62,6 +62,17 @@ describe("toTamaraCheckoutRequest", () => {
 			"https://shop.example.com/api/auth/bnpl/webhooks/tamara",
 		);
 	});
+	it("rejects checkout without a shipping address with a typed error", () => {
+		const { shippingAddress: _shippingAddress, ...input } = baseCheckout;
+
+		expect(() => toTamaraCheckoutRequest(input)).toThrowError(
+			expect.objectContaining({
+				name: "BnplPluginError",
+				code: "PROVIDER_NOT_AVAILABLE",
+				message: "tamara: shippingAddress is required",
+			}),
+		);
+	});
 });
 describe("tamaraStatusToCanonical", () => {
 	it("passes through canonical statuses", () => {

src/core/types.ts

@@ -62,7 +62,7 @@ export interface BnplCheckoutInput {
 	discount?: BnplDiscount;
 	items: NonEmptyArray<BnplOrderItem>;
 	buyer: BnplBuyer;
-	shippingAddress: BnplAddress;
+	shippingAddress?: BnplAddress;
 	billingAddress?: BnplAddress;
 	countryCode: string;
 	locale?: BnplLocale;

src/plugins/checkout.ts

@@ -40,7 +40,7 @@ const sharedFields = {
 	orderReferenceId: z.string().optional(),
 	description: z.string().max(256),
 	buyer: buyerSchema.optional(),
-	shippingAddress: addressSchema,
+	shippingAddress: addressSchema.optional(),
 	billingAddress: addressSchema.optional(),
 	countryCode: z.string().min(2).max(2),
 	locale: localeSchema.optional(),

src/providers/tabby/adapter.ts

@@ -120,7 +120,9 @@ export function toTabbyCheckoutRequest(
 			currency: input.totalAmount.currency,
 			description: input.description,
 			buyer: toTabbyBuyer(input.buyer),
-			shipping_address: toTabbyShippingAddress(input.shippingAddress),
+			...(input.shippingAddress
+				? { shipping_address: toTabbyShippingAddress(input.shippingAddress) }
+				: {}),
 			order: {
 				reference_id: input.orderReferenceId,
 				tax_amount: input.taxAmount?.amount,

src/providers/tabby/schemas.ts

@@ -102,7 +102,7 @@ export const tabbyCheckoutCreationOrderHistorySchema = z
 		payment_method: z.enum(["card", "cod"]).optional(),
 		status: z.enum(["new", "processing", "complete", "refunded", "canceled", "unknown"]),
 		buyer: tabbyHistoryBuyerSchema,
-		shipping_address: tabbyHistoryShippingAddressSchema,
+		shipping_address: tabbyHistoryShippingAddressSchema.optional(),
 		items: z.array(tabbyOrderItemHistorySchema).optional(),
 	})
 	.strict();
@@ -151,7 +151,7 @@ export const tabbyPaymentRequestSchema = z.object({
 	currency: nonEmptyStringSchema,
 	description: z.string().optional(),
 	buyer: tabbyBuyerRequestSchema,
-	shipping_address: tabbyShippingAddressRequestSchema,
+	shipping_address: tabbyShippingAddressRequestSchema.optional(),
 	order: tabbyOrderRequestSchema,
 	buyer_history: tabbyBuyerHistoryRequestSchema.optional(),
 	order_history: z.array(tabbyCheckoutCreationOrderHistorySchema).max(10).optional(),

src/providers/tamara/adapter.ts

@@ -98,6 +98,9 @@ export function toTamaraCheckoutRequest(
 	input: BnplCheckoutInput,
 	opts: ToTamaraCheckoutOptions = {},
 ): TamaraCheckoutRequest {
+	if (!input.shippingAddress) {
+		throw new BnplPluginError("PROVIDER_NOT_AVAILABLE", "tamara: shippingAddress is required");
+	}
 	const locale = input.locale ? LOCALE_MAP[input.locale] : opts.defaultLocale;
 	return {
 		order_reference_id: input.orderReferenceId,