@develemit/commerce-server 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.9.0 (2026-11-14)
+
+### Features
+
+- Products can carry an optional Stripe `taxCode`. Migration `0011` adds `commerce_products.tax_code`; the admin API reads and writes it, checkout sends it on that line (`CheckoutLine.taxCode`, which the Stripe gateway passes as `tax_code`), and the public catalog does not expose it.
+- `orderEmailLines` adds a `tax` line (structured, text and HTML, label `labels.tax`, default "Tax") between shipping and total, only when the order's `taxCents` is above 0.
+- Opt-in automatic sales tax through Stripe Tax: `createStripeGateway({ tax: { enabled: true, behavior?, shippingTaxCode? } })` (or `resolvePayment(env, { tax })`) sets `automatic_tax`, a `tax_behavior` on every line and shipping option, and a per-line `taxCode` (`CheckoutLine.taxCode`) when present. The completed-session webhook reads `total_details.amount_tax` into `taxCents`. Without the option, sessions are unchanged. The fake gateway accepts `tax: { rate }` and `taxFor()`, and `devCheckout` records the computed tax.
+- Orders record sales tax. Migration `0010` adds `commerce_orders.tax_cents` (default 0). A `checkout.completed` `PaymentEvent` may carry `taxCents`; it is stored on the order and included in `totalCents`, so full refunds return the tax. Public and admin order responses return `taxCents`. The fake gateway's `completed()` accepts `taxCents`.
+
 ## 0.8.0 (2026-11-12)
 
 ### Features

package/README.md

@@ -136,7 +136,8 @@ onOrderPaid: async (order) => {
 `formatOrderRef` in contracts); print it instead of the full id.
 
 The result also has structured `items`, `subtotal`, `discount` (absent when
-no discount applied), `shipping`, `total` and `address` (absent for pickup).
+no discount applied), `shipping`, `tax` (absent when the order has no tax), `total` and `address`
+(absent for pickup).
 HTML output is `<tr>` / `<p>` fragments with `& < > " '` escaped. Override
 copy with `labels`.
 

package/dist/index.d.ts

@@ -214,6 +214,23 @@ declare const commerceSchema: {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            taxCode: drizzle_orm_pg_core.PgColumn<{
+                name: "tax_code";
+                tableName: "commerce_products";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             publishedAt: drizzle_orm_pg_core.PgColumn<{
                 name: "published_at";
                 tableName: "commerce_products";
@@ -645,6 +662,23 @@ declare const commerceSchema: {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            taxCents: drizzle_orm_pg_core.PgColumn<{
+                name: "tax_cents";
+                tableName: "commerce_orders";
+                dataType: "number";
+                columnType: "PgInteger";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             currency: drizzle_orm_pg_core.PgColumn<{
                 name: "currency";
                 tableName: "commerce_orders";
@@ -1686,6 +1720,7 @@ interface CheckoutLine {
     name: string;
     unitAmountCents: number;
     quantity: number;
+    taxCode?: string;
 }
 interface CreateCheckoutSessionInput {
     reference: string;
@@ -1731,6 +1766,7 @@ type PaymentEvent = {
     email?: string;
     shippingAddress?: ShippingAddress;
     shipping?: ChosenShipping;
+    taxCents?: number;
     paymentPending?: boolean;
 } | {
     id: string;
@@ -1844,8 +1880,14 @@ interface StripeGatewayOptions {
     secretKey: string;
     webhookSecret: string;
     client?: Stripe;
+    tax?: StripeTaxOptions;
+}
+interface StripeTaxOptions {
+    enabled: true;
+    behavior?: 'exclusive' | 'inclusive';
+    shippingTaxCode?: string;
 }
-declare function createStripeGateway({ secretKey, webhookSecret, client, }: StripeGatewayOptions): PaymentGateway;
+declare function createStripeGateway({ secretKey, webhookSecret, client, tax, }: StripeGatewayOptions): PaymentGateway;
 
 interface SignedWebhook {
     rawBody: Buffer;
@@ -1868,6 +1910,7 @@ interface FakeGateway extends PaymentGateway {
         email?: string;
         shippingAddress?: ShippingAddress;
         shipping?: ChosenShipping;
+        taxCents?: number;
         paymentPending?: boolean;
     }): SignedWebhook;
     asyncPaid(sessionId: string): SignedWebhook;
@@ -1875,11 +1918,16 @@ interface FakeGateway extends PaymentGateway {
     expired(sessionId: string): SignedWebhook;
     refunded(sessionId: string, refunds: GatewayRefundEvent[]): SignedWebhook;
     sign(event: PaymentEvent): SignedWebhook;
+    taxFor(sessionId: string, shippingCents?: number): number;
+}
+interface FakeTaxOptions {
+    rate: number;
 }
 interface FakeGatewayOptions {
     secret?: string;
+    tax?: FakeTaxOptions;
 }
-declare function createFakeGateway({ secret, }?: FakeGatewayOptions): FakeGateway;
+declare function createFakeGateway({ secret, tax, }?: FakeGatewayOptions): FakeGateway;
 declare function isFakeGateway(gateway: PaymentGateway): gateway is FakeGateway;
 
 interface HoldSweeperOptions {
@@ -1899,6 +1947,7 @@ interface OrderEmailLabels {
     subtotal: string;
     discount: (code: string | null) => string;
     shipping: (label: string | null) => string;
+    tax: string;
     total: string;
 }
 interface OrderEmailLinesOptions {
@@ -1921,6 +1970,7 @@ interface OrderEmailLines {
     subtotal: EmailLine;
     discount?: EmailLine;
     shipping: EmailLine;
+    tax?: EmailLine;
     total: EmailLine;
     address?: string[];
     text: OrderEmailLinesText;
@@ -1986,7 +2036,11 @@ interface PaymentEnv {
     STRIPE_SECRET_KEY?: string;
     STRIPE_WEBHOOK_SECRET?: string;
 }
-declare function resolvePayment(env?: PaymentEnv): PaymentGateway;
+interface ResolvePaymentOptions {
+    tax?: StripeTaxOptions;
+    fakeTax?: FakeTaxOptions;
+}
+declare function resolvePayment(env?: PaymentEnv, { tax, fakeTax }?: ResolvePaymentOptions): PaymentGateway;
 interface CheckoutUrlPaths {
     successPath?: string;
     cancelPath?: string;
@@ -1994,4 +2048,4 @@ interface CheckoutUrlPaths {
 declare function checkoutUrls(webUrl: string, { successPath, cancelPath, }?: CheckoutUrlPaths): CheckoutUrls;
 
 export { ProductNotFoundError, SESSION_ID_PLACEHOLDER, WebhookSignatureError, catalogPlugin, checkoutUrls, commercePlugin, commerceSchema, createDiskStorage, createFakeGateway, createMemoryStorage, createStripeGateway, isFakeGateway, openStoredFile, orderEmailLines, ordersPlugin, resolvePayment, runCommerceMigrations, seedProducts, seedShippingRates, startHoldSweeper };
-export type { AdminOptions, CatalogCacheOptions, CatalogPluginOptions, CategoryLabels, CheckoutDiscount, CheckoutLine, CheckoutSession, CheckoutUrlPaths, CheckoutUrls, ChosenShipping, CommerceDb, CommercePluginOptions, CommerceSchema, CreateCheckoutSessionInput, DevBuyer, DevBuyerSetting, DevCheckoutSetting, DiskStorageOptions, EmailLine, FakeGateway, FakeGatewayOptions, FileStorage, GatewayRefund, HoldSweeper, HoldSweeperOptions, MemoryStorage, OrderEmailLabels, OrderEmailLines, OrderEmailLinesOptions, OrderHooks, OrdersPluginOptions, PaymentEnv, PaymentEvent, PaymentGateway, RefundInput, SeedProduct, SeedShippingRate, ShippingAddress, ShippingRateOption, SignedWebhook, StoredFile, StoredFileStream, StripeGatewayOptions };
+export type { AdminOptions, CatalogCacheOptions, CatalogPluginOptions, CategoryLabels, CheckoutDiscount, CheckoutLine, CheckoutSession, CheckoutUrlPaths, CheckoutUrls, ChosenShipping, CommerceDb, CommercePluginOptions, CommerceSchema, CreateCheckoutSessionInput, DevBuyer, DevBuyerSetting, DevCheckoutSetting, DiskStorageOptions, EmailLine, FakeGateway, FakeGatewayOptions, FakeTaxOptions, FileStorage, GatewayRefund, HoldSweeper, HoldSweeperOptions, MemoryStorage, OrderEmailLabels, OrderEmailLines, OrderEmailLinesOptions, OrderHooks, OrdersPluginOptions, PaymentEnv, PaymentEvent, PaymentGateway, RefundInput, ResolvePaymentOptions, SeedProduct, SeedShippingRate, ShippingAddress, ShippingRateOption, SignedWebhook, StoredFile, StoredFileStream, StripeGatewayOptions, StripeTaxOptions };

package/dist/index.js

@@ -82,6 +82,7 @@ var products = pgTable(
     quantity: integer("quantity").notNull().default(1),
     status: productStatus("status").notNull().default("draft"),
     featured: boolean("featured").notNull().default(false),
+    taxCode: text("tax_code"),
     publishedAt: timestamp("published_at", { withTimezone: true }),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
@@ -139,6 +140,7 @@ var orders = pgTable("commerce_orders", {
   discountCode: text("discount_code"),
   shippingCents: integer("shipping_cents").notNull().default(0),
   shippingLabel: text("shipping_label"),
+  taxCents: integer("tax_cents").notNull().default(0),
   currency: text("currency").notNull(),
   checkoutSessionId: text("checkout_session_id").unique(),
   shippingAddress: jsonb("shipping_address"),
@@ -548,6 +550,7 @@ function toAdminProduct({ row, images }) {
     status: row.status,
     featured: row.featured,
     everPublished: row.publishedAt !== null,
+    taxCode: row.taxCode,
     images: images.map((i) => ({
       id: i.id,
       url: i.url,
@@ -1226,7 +1229,8 @@ async function findPurchasable(db, ids) {
     id: row.id,
     name: row.name,
     priceCents: completeFields(row).priceCents,
-    currency: row.currency
+    currency: row.currency,
+    taxCode: row.taxCode
   }));
 }
 
@@ -1318,7 +1322,8 @@ async function selectOrderPage(db, filter) {
     id: orders.id,
     status: orders.status,
     email: orders.email,
-    totalCents: sql5`${orders.subtotalCents} - ${orders.discountCents} + ${orders.shippingCents}`,
+    taxCents: orders.taxCents,
+    totalCents: sql5`${orders.subtotalCents} - ${orders.discountCents} + ${orders.shippingCents} + ${orders.taxCents}`,
     currency: orders.currency,
     itemCount,
     createdAt: orders.createdAt,
@@ -1341,7 +1346,7 @@ var isRecordedRefund = or4(
 async function lockOrderForRefund(tx, id) {
   const [row] = await tx.select({
     status: orders.status,
-    totalCents: sql6`${orders.subtotalCents} - ${orders.discountCents} + ${orders.shippingCents}`,
+    totalCents: sql6`${orders.subtotalCents} - ${orders.discountCents} + ${orders.shippingCents} + ${orders.taxCents}`,
     currency: orders.currency,
     checkoutSessionId: orders.checkoutSessionId
   }).from(orders).where(eq6(orders.id, id)).for("update");
@@ -1433,6 +1438,7 @@ async function saveOrderDetails(db, orderId, details, status) {
     shippingAddress: details.shippingAddress ?? null,
     shippingCents: details.shipping?.amountCents ?? 0,
     shippingLabel: details.shipping?.label ?? null,
+    taxCents: details.taxCents ?? 0,
     updatedAt: sql7`now()`
   }).where(eq7(orders.id, orderId));
 }
@@ -1478,7 +1484,8 @@ async function toSummary(db, order) {
     discountCode: order.discountCode,
     shippingCents: order.shippingCents,
     shippingLabel: order.shippingLabel,
-    totalCents: order.subtotalCents - order.discountCents + order.shippingCents,
+    taxCents: order.taxCents,
+    totalCents: order.subtotalCents - order.discountCents + order.shippingCents + order.taxCents,
     currency: order.currency,
     items: items.map((i) => ({
       productId: i.productId,
@@ -1558,6 +1565,7 @@ async function listAdminOrders(db, query) {
       id: r.id,
       status: r.status,
       email: r.email,
+      taxCents: r.taxCents,
       totalCents: r.totalCents,
       currency: r.currency,
       itemCount: r.itemCount,
@@ -2536,6 +2544,15 @@ function assertDevCheckoutAllowed() {
     throw new Error("devCheckout is not allowed when NODE_ENV=production");
   }
 }
+function completedWithTax(payment, session, buyer) {
+  const details = resolveDevCompletion(
+    buyer,
+    session.id,
+    session.shippingRates[0]
+  );
+  const taxCents = payment.taxFor(session.id, details.shipping?.amountCents);
+  return payment.completed(session.id, { ...details, taxCents });
+}
 var devCheckoutRoutes = async (app, { db, payment, urls, hooks, buyer }) => {
   assertDevCheckoutAllowed();
   app.get("/checkout/dev/:sessionId/complete", async (req, reply) => {
@@ -2545,10 +2562,7 @@ var devCheckoutRoutes = async (app, { db, payment, urls, hooks, buyer }) => {
       return reply.code(404).send({ error: "SESSION_NOT_FOUND" });
     }
     const expire = req.query.outcome === "expired";
-    const { rawBody, signature } = expire ? payment.expired(sessionId) : payment.completed(
-      sessionId,
-      resolveDevCompletion(buyer, sessionId, session.shippingRates[0])
-    );
+    const { rawBody, signature } = expire ? payment.expired(sessionId) : completedWithTax(payment, session, buyer);
     const event = await payment.verifyWebhook(rawBody, signature);
     await handlePaymentEvent(db, event, hooks, req.log);
     return reply.redirect(expire ? urls.cancel : urls.success(sessionId), 302);
@@ -2632,7 +2646,8 @@ async function priceLines(db, requests, currency) {
       productId,
       name: product.name,
       unitAmountCents: product.priceCents,
-      quantity
+      quantity,
+      ...product.taxCode && { taxCode: product.taxCode }
     };
   });
 }
@@ -2822,7 +2837,8 @@ var ordersPlugin = async (app, { db, ...settings }) => {
 // src/payment/fake-gateway.ts
 import { createHmac, randomUUID as randomUUID4, timingSafeEqual } from "crypto";
 function createFakeGateway({
-  secret = "fake-webhook-secret"
+  secret = "fake-webhook-secret",
+  tax
 } = {}) {
   const sessions = [];
   const refunds = [];
@@ -2925,7 +2941,17 @@ function createFakeGateway({
         refunds: refunds2
       });
     },
-    sign
+    sign,
+    taxFor(sessionId, shippingCents = 0) {
+      const session = sessions.find((s) => s.id === sessionId);
+      if (!tax || !session) return 0;
+      const merchandise = session.lines.reduce(
+        (sum, l) => sum + l.unitAmountCents * l.quantity,
+        0
+      );
+      const taxable = merchandise - (session.discount?.amountCents ?? 0) + shippingCents;
+      return Math.round(taxable * tax.rate);
+    }
   };
 }
 function isFakeGateway(gateway) {
@@ -3041,13 +3067,17 @@ function toShippingAddress(name, address) {
     Object.entries(fields).filter(([, v]) => v !== void 0)
   );
 }
-function toShippingOption(rate, currency) {
+function toShippingOption(rate, currency, tax) {
   const days = (value) => ({ unit: "business_day", value });
   return {
     shipping_rate_data: {
       type: "fixed_amount",
       display_name: rate.label,
       fixed_amount: { amount: rate.amountCents, currency },
+      ...tax && {
+        tax_behavior: tax.behavior ?? "exclusive",
+        ...tax.shippingTaxCode && { tax_code: tax.shippingTaxCode }
+      },
       ...rate.minDays !== void 0 && rate.maxDays !== void 0 && {
         delivery_estimate: {
           minimum: days(rate.minDays),
@@ -3063,7 +3093,7 @@ function toChosenShipping(session) {
   if (!cost || !rate || typeof rate === "string") return void 0;
   return {
     label: rate.display_name ?? "Shipping",
-    amountCents: cost.amount_total
+    amountCents: cost.amount_subtotal
   };
 }
 function toPaymentEvent(event, expanded) {
@@ -3077,6 +3107,9 @@ function toPaymentEvent(event, expanded) {
       email: session.customer_details?.email ?? void 0,
       shippingAddress: toShippingAddress(shipping?.name, shipping?.address),
       shipping: expanded && toChosenShipping(expanded),
+      ...session.total_details && {
+        taxCents: session.total_details.amount_tax
+      },
       paymentPending: session.payment_status === "unpaid"
     };
   }
@@ -3145,7 +3178,8 @@ function createCoupon(stripe, { discount, currency, expiresAt }) {
 function createStripeGateway({
   secretKey,
   webhookSecret,
-  client
+  client,
+  tax
 }) {
   let stripe = client ? Promise.resolve(client) : void 0;
   const getStripe = () => stripe ??= loadStripe(secretKey);
@@ -3165,19 +3199,22 @@ function createStripeGateway({
           price_data: {
             currency: input.currency.toLowerCase(),
             unit_amount: line.unitAmountCents,
+            ...tax && { tax_behavior: tax.behavior ?? "exclusive" },
             product_data: {
               name: line.name,
-              metadata: { productId: line.productId }
+              metadata: { productId: line.productId },
+              ...tax && line.taxCode && { tax_code: line.taxCode }
             }
           }
         })),
+        ...tax && { automatic_tax: { enabled: true } },
         ...coupon && { discounts: [{ coupon: coupon.id }] },
         success_url: input.successUrl,
         cancel_url: input.cancelUrl,
         expires_at: Math.floor(input.expiresAt.getTime() / 1e3),
         ...input.shippingRates.length > 0 && {
           shipping_options: input.shippingRates.map(
-            (rate) => toShippingOption(rate, input.currency.toLowerCase())
+            (rate) => toShippingOption(rate, input.currency.toLowerCase(), tax)
           )
         },
         shipping_address_collection: {
@@ -3257,6 +3294,7 @@ var defaultLabels = {
   subtotal: "Subtotal",
   discount: (code) => code ? `Discount (${code})` : "Discount",
   shipping: (label) => label ? `Shipping (${label})` : "Shipping",
+  tax: "Tax",
   total: "Total"
 };
 var escapes = {
@@ -3312,15 +3350,23 @@ function orderEmailLines(order, options = {}) {
     label: labels.shipping(order.shippingLabel),
     amount: money(order.shippingCents)
   };
+  const tax = order.taxCents > 0 ? { label: labels.tax, amount: money(order.taxCents) } : void 0;
   const total = { label: labels.total, amount: money(order.totalCents) };
   const address = addressLines(order);
-  const totals = [subtotal, ...discount ? [discount] : [], shipping, total];
+  const totals = [
+    subtotal,
+    ...discount ? [discount] : [],
+    shipping,
+    ...tax ? [tax] : [],
+    total
+  ];
   return {
     reference: formatOrderRef(order.id),
     items,
     subtotal,
     discount,
     shipping,
+    tax,
     total,
     address,
     text: {
@@ -3492,7 +3538,7 @@ async function openStoredFile(dir, key) {
 }
 
 // src/payment/resolve.ts
-function resolvePayment(env = process.env) {
+function resolvePayment(env = process.env, { tax, fakeTax } = {}) {
   const secretKey = env.STRIPE_SECRET_KEY || void 0;
   const webhookSecret = env.STRIPE_WEBHOOK_SECRET || void 0;
   if (!secretKey !== !webhookSecret) {
@@ -3509,9 +3555,13 @@ function resolvePayment(env = process.env) {
         "The fake payment gateway is not allowed in production; set the Stripe keys"
       );
     }
-    return createFakeGateway();
+    return createFakeGateway({ tax: fakeTax });
   }
-  return createStripeGateway({ secretKey, webhookSecret });
+  return createStripeGateway({
+    secretKey,
+    webhookSecret,
+    tax
+  });
 }
 function checkoutUrls(webUrl, {
   successPath = "/checkout/success",