@develemit/commerce-server 0.4.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:

package/dist/index.d.ts

@@ -1780,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;
@@ -1820,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;
     })[];
@@ -1846,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;
@@ -1856,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 {
@@ -1896,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, CheckoutDiscount, 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 };