@develemit/commerce-server 0.3.0 → 0.6.0

package/README.md

@@ -51,6 +51,11 @@ const sweeper = startHoldSweeper(db, { intervalMs: 60_000 });
 app.addHook('onClose', async () => sweeper.stop());
 ```
 
+`resolvePayment(process.env)` picks Stripe or the fake gateway from the
+environment (it refuses the fake gateway when `NODE_ENV=production` and
+half-configured Stripe keys), and `checkoutUrls(webUrl)` builds the `urls`
+option; use them instead of hand-writing both.
+
 `payment` and `urls` go together. Omit both (`commercePlugin({ db, currency })`)
 for a catalog-only mount: the checkout, webhook, and order routes aren't
 registered, so `/checkout` returns 404.
@@ -105,6 +110,28 @@ matters.
 The package never reads `process.env`; pass everything in. Load products with
 `seedProducts(db, products)`, an idempotent upsert on `slug`.
 
+## Order emails
+
+`orderEmailLines(order, { locale, labels })` builds the money and address
+pieces of an order email from the `OrderDetail` a hook receives. You write the
+layout and copy.
+
+```ts
+onOrderPaid: async (order) => {
+  const lines = orderEmailLines(order);
+  await mailer.send({
+    to: order.email,
+    text: `${lines.text.items}\n${lines.text.totals}\n\n${lines.text.address}`,
+    html: `<table>${lines.html.items}${lines.html.totals}</table>${lines.html.address}`,
+  });
+},
+```
+
+The result also has structured `items`, `subtotal`, `discount` (absent when
+no discount applied), `shipping`, `total` and `address` (absent for pickup).
+HTML output is `<tr>` / `<p>` fragments with `& < > " '` escaped. Override
+copy with `labels`.
+
 ## Running a shop
 
 The order lifecycle, from the host's side:
@@ -161,20 +188,36 @@ app root before `commercePlugin`, so its `onSend` runs after the catalog's.
   Webhook raw-body parsing is request-side and unaffected by compression.
 - **Retries:** refunds require an `Idempotency-Key`; reuse it when retrying so
   a refund can't be issued twice.
+- **Rate limiting:** `POST /checkout/discount/preview` lets anyone test codes.
+  Rate-limit it (and `POST /checkout`) at the host or CDN; the kit doesn't.
 - Admin routes: see [Admin API](docs/admin.md).
 
 ## Routes
 
 Relative to the host's prefix:
 
-| Route                            | Purpose                                                    |
-| -------------------------------- | ---------------------------------------------------------- |
-| `GET /catalog/products`          | Active products (`?category=`, `?featured=true`)           |
-| `GET /catalog/products/:slug`    | One product, or 404 `PRODUCT_NOT_FOUND`                    |
-| `GET /catalog/categories`        | Active product counts per category                         |
-| `POST /checkout`                 | `{ items: [{ productId, quantity }] }` → `{ url }`, or 409 |
-| `POST /orders/webhooks/stripe`   | Stripe webhook (raw body, `stripe-signature` header)       |
-| `GET /orders/session/:sessionId` | `orderSummarySchema` for the success page                  |
+| Route                             | Purpose                                                         |
+| --------------------------------- | --------------------------------------------------------------- |
+| `GET /catalog/products`           | Active products (`?category=`, `?featured=true`)                |
+| `GET /catalog/products/:slug`     | One product, or 404 `PRODUCT_NOT_FOUND`                         |
+| `GET /catalog/categories`         | Active product counts per category                              |
+| `POST /checkout`                  | `{ items: [{ productId, quantity }] }` → `{ url }`, or 409      |
+| `POST /checkout/discount/preview` | `{ code, items }` → discount preview, or 422 `DISCOUNT_INVALID` |
+| `POST /orders/webhooks/stripe`    | Stripe webhook (raw body, `stripe-signature` header)            |
+| `GET /orders/session/:sessionId`  | `orderSummarySchema` for the success page                       |
+
+## Discounts
+
+`POST /checkout/discount/preview` takes `{ code, items }` and answers
+`{ code, discountCents, subtotalCents, currency }`, or 422
+`{ error: 'DISCOUNT_INVALID', reason }`. The subtotal is priced from the
+database over the items that are currently purchasable in the shop currency;
+unavailable items are left out, matching what checkout would charge. Rules run
+in order and the first failure wins: not found, inactive, not started, expired,
+currency (fixed codes), minimum subtotal, redemptions exhausted. Percent codes
+round down; fixed codes never exceed the subtotal; shipping is never
+discounted. An inactive code is reported as `not_found` so drafts don't leak.
+Responses are `Cache-Control: no-store`.
 
 ## How checkout stays honest
 

package/dist/index.d.ts

@@ -560,6 +560,40 @@ declare const commerceSchema: {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            discountCents: drizzle_orm_pg_core.PgColumn<{
+                name: "discount_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;
+            }, {}, {}>;
+            discountCode: drizzle_orm_pg_core.PgColumn<{
+                name: "discount_code";
+                tableName: "commerce_orders";
+                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;
+            }, {}, {}>;
             shippingCents: drizzle_orm_pg_core.PgColumn<{
                 name: "shipping_cents";
                 tableName: "commerce_orders";
@@ -1238,6 +1272,360 @@ declare const commerceSchema: {
         };
         dialect: "pg";
     }>;
+    discounts: drizzle_orm_pg_core.PgTableWithColumns<{
+        name: "commerce_discounts";
+        schema: undefined;
+        columns: {
+            id: drizzle_orm_pg_core.PgColumn<{
+                name: "id";
+                tableName: "commerce_discounts";
+                dataType: "string";
+                columnType: "PgUUID";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: true;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            code: drizzle_orm_pg_core.PgColumn<{
+                name: "code";
+                tableName: "commerce_discounts";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            type: drizzle_orm_pg_core.PgColumn<{
+                name: "type";
+                tableName: "commerce_discounts";
+                dataType: "string";
+                columnType: "PgText";
+                data: "fixed" | "percent";
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: ["percent", "fixed"];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            percentOff: drizzle_orm_pg_core.PgColumn<{
+                name: "percent_off";
+                tableName: "commerce_discounts";
+                dataType: "number";
+                columnType: "PgInteger";
+                data: number;
+                driverParam: string | number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            amountOffCents: drizzle_orm_pg_core.PgColumn<{
+                name: "amount_off_cents";
+                tableName: "commerce_discounts";
+                dataType: "number";
+                columnType: "PgInteger";
+                data: number;
+                driverParam: string | number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            currency: drizzle_orm_pg_core.PgColumn<{
+                name: "currency";
+                tableName: "commerce_discounts";
+                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;
+            }, {}, {}>;
+            minSubtotalCents: drizzle_orm_pg_core.PgColumn<{
+                name: "min_subtotal_cents";
+                tableName: "commerce_discounts";
+                dataType: "number";
+                columnType: "PgInteger";
+                data: number;
+                driverParam: string | number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            startsAt: drizzle_orm_pg_core.PgColumn<{
+                name: "starts_at";
+                tableName: "commerce_discounts";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            endsAt: drizzle_orm_pg_core.PgColumn<{
+                name: "ends_at";
+                tableName: "commerce_discounts";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            maxRedemptions: drizzle_orm_pg_core.PgColumn<{
+                name: "max_redemptions";
+                tableName: "commerce_discounts";
+                dataType: "number";
+                columnType: "PgInteger";
+                data: number;
+                driverParam: string | number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            active: drizzle_orm_pg_core.PgColumn<{
+                name: "active";
+                tableName: "commerce_discounts";
+                dataType: "boolean";
+                columnType: "PgBoolean";
+                data: boolean;
+                driverParam: boolean;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            createdAt: drizzle_orm_pg_core.PgColumn<{
+                name: "created_at";
+                tableName: "commerce_discounts";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            updatedAt: drizzle_orm_pg_core.PgColumn<{
+                name: "updated_at";
+                tableName: "commerce_discounts";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+        };
+        dialect: "pg";
+    }>;
+    discountRedemptions: drizzle_orm_pg_core.PgTableWithColumns<{
+        name: "commerce_discount_redemptions";
+        schema: undefined;
+        columns: {
+            id: drizzle_orm_pg_core.PgColumn<{
+                name: "id";
+                tableName: "commerce_discount_redemptions";
+                dataType: "string";
+                columnType: "PgUUID";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: true;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            discountId: drizzle_orm_pg_core.PgColumn<{
+                name: "discount_id";
+                tableName: "commerce_discount_redemptions";
+                dataType: "string";
+                columnType: "PgUUID";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            orderId: drizzle_orm_pg_core.PgColumn<{
+                name: "order_id";
+                tableName: "commerce_discount_redemptions";
+                dataType: "string";
+                columnType: "PgUUID";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            status: drizzle_orm_pg_core.PgColumn<{
+                name: "status";
+                tableName: "commerce_discount_redemptions";
+                dataType: "string";
+                columnType: "PgText";
+                data: "released" | "committed" | "reserved";
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: ["reserved", "committed", "released"];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            amountCents: drizzle_orm_pg_core.PgColumn<{
+                name: "amount_cents";
+                tableName: "commerce_discount_redemptions";
+                dataType: "number";
+                columnType: "PgInteger";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            createdAt: drizzle_orm_pg_core.PgColumn<{
+                name: "created_at";
+                tableName: "commerce_discount_redemptions";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            updatedAt: drizzle_orm_pg_core.PgColumn<{
+                name: "updated_at";
+                tableName: "commerce_discount_redemptions";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+        };
+        dialect: "pg";
+    }>;
 };
 type CommerceSchema = typeof commerceSchema;
 
@@ -1290,6 +1678,11 @@ interface CreateCheckoutSessionInput {
     shippingCountries: string[];
     shippingRates: ShippingRateOption[];
     expiresAt: Date;
+    discount?: CheckoutDiscount;
+}
+interface CheckoutDiscount {
+    code: string;
+    amountCents: number;
 }
 interface CheckoutSession {
     id: string;
@@ -1387,12 +1780,17 @@ interface CheckoutOptions {
     urls: CheckoutUrls;
     shippingCountries?: string[];
     hooks?: OrderHooks;
+    devCheckout?: boolean | DevCheckoutSetting;
+}
+interface DevCheckoutSetting {
+    apiUrl?: string;
 }
 interface CatalogOnlyOptions {
     payment?: undefined;
     urls?: undefined;
     shippingCountries?: undefined;
     hooks?: undefined;
+    devCheckout?: undefined;
 }
 type CommercePluginOptions = {
     db: CommerceDb;
@@ -1427,6 +1825,8 @@ interface SignedWebhook {
     signature: string;
 }
 interface FakeGateway extends PaymentGateway {
+    readonly kind: 'fake';
+    useSessionUrl(build: (sessionId: string) => string): void;
     readonly sessions: (CreateCheckoutSessionInput & {
         id: string;
     })[];
@@ -1453,6 +1853,7 @@ interface FakeGatewayOptions {
     secret?: string;
 }
 declare function createFakeGateway({ secret, }?: FakeGatewayOptions): FakeGateway;
+declare function isFakeGateway(gateway: PaymentGateway): gateway is FakeGateway;
 
 interface HoldSweeperOptions {
     intervalMs?: number;
@@ -1463,6 +1864,42 @@ interface HoldSweeper {
 }
 declare function startHoldSweeper(db: CommerceDb, { intervalMs, onError }?: HoldSweeperOptions): HoldSweeper;
 
+interface EmailLine {
+    label: string;
+    amount: string;
+}
+interface OrderEmailLabels {
+    subtotal: string;
+    discount: (code: string | null) => string;
+    shipping: (label: string | null) => string;
+    total: string;
+}
+interface OrderEmailLinesOptions {
+    locale?: string;
+    labels?: Partial<OrderEmailLabels>;
+}
+interface OrderEmailLinesText {
+    items: string;
+    totals: string;
+    address: string;
+}
+interface OrderEmailLinesHtml {
+    items: string;
+    totals: string;
+    address: string;
+}
+interface OrderEmailLines {
+    items: EmailLine[];
+    subtotal: EmailLine;
+    discount?: EmailLine;
+    shipping: EmailLine;
+    total: EmailLine;
+    address?: string[];
+    text: OrderEmailLinesText;
+    html: OrderEmailLinesHtml;
+}
+declare function orderEmailLines(order: OrderDetail, options?: OrderEmailLinesOptions): OrderEmailLines;
+
 declare function runCommerceMigrations(db: NodePgDatabase<any>): Promise<void>;
 
 interface SeedProduct {
@@ -1503,5 +1940,30 @@ interface MemoryStorage extends FileStorage {
 }
 declare function createMemoryStorage(baseUrl?: string): MemoryStorage;
 
-export { ProductNotFoundError, SESSION_ID_PLACEHOLDER, WebhookSignatureError, catalogPlugin, commercePlugin, commerceSchema, createFakeGateway, createMemoryStorage, createStripeGateway, ordersPlugin, runCommerceMigrations, seedProducts, seedShippingRates, startHoldSweeper };
-export type { AdminOptions, CatalogCacheOptions, CatalogPluginOptions, CategoryLabels, CheckoutLine, CheckoutSession, CheckoutUrls, ChosenShipping, CommerceDb, CommercePluginOptions, CommerceSchema, CreateCheckoutSessionInput, FakeGateway, FakeGatewayOptions, FileStorage, GatewayRefund, HoldSweeper, HoldSweeperOptions, MemoryStorage, OrderHooks, OrdersPluginOptions, PaymentEvent, PaymentGateway, RefundInput, SeedProduct, SeedShippingRate, ShippingAddress, ShippingRateOption, SignedWebhook, StoredFile, StripeGatewayOptions };
+interface DiskStorageOptions {
+    dir: string;
+    publicUrl: string;
+}
+interface StoredFileStream {
+    stream: Readable;
+    contentType: string | undefined;
+    size: number;
+}
+declare function createDiskStorage(options: DiskStorageOptions): FileStorage;
+declare function openStoredFile(dir: string, key: string): Promise<StoredFileStream | null>;
+
+interface PaymentEnv {
+    NODE_ENV?: string;
+    PAYMENT_GATEWAY?: string;
+    STRIPE_SECRET_KEY?: string;
+    STRIPE_WEBHOOK_SECRET?: string;
+}
+declare function resolvePayment(env?: PaymentEnv): PaymentGateway;
+interface CheckoutUrlPaths {
+    successPath?: string;
+    cancelPath?: string;
+}
+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, 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 };