create-nextblock 0.2.77 → 0.8.0

package/templates/nextblock-template/docs/02-ECOMMERCE-CAPABILITIES.md

@@ -0,0 +1,364 @@
+# 02 Ecommerce Capabilities
+
+## Scope and Source of Truth
+
+The commerce feature set is implemented across:
+
+- `libs/ecommerce/src/lib/*`
+- `libs/db/src/supabase/migrations/00000000000003` through `00000000000006`
+- `apps/nextblock/app/api/checkout/route.ts`
+- `apps/nextblock/app/api/webhooks/*`
+- `apps/nextblock/app/cms/products`, `orders`, `shipping`, `payments`, and
+  `settings/taxes`
+
+In workspace code, the developer-facing import paths are:
+
+- `@nextblock-cms/ecommerce`
+- `@nextblock-cms/ecommerce/server`
+- `@nextblock-cms/ecommerce/actions`
+
+One packaging discrepancy exists today: `libs/ecommerce/package.json` is still
+named `@nextblock-cms/ecom`, while the workspace and CLI activation flow expose
+the package through the `@nextblock-cms/ecommerce` alias.
+
+## Commerce Data Model
+
+The commerce schema spans:
+
+- Catalog: `products`, `product_media`, `product_attributes`,
+  `product_attribute_terms`, `product_variants`,
+  `variant_attribute_mapping`, `categories`, `product_categories`
+  (categories and their translations were added by migrations
+  `00000000000019` and `00000000000020`)
+- Inventory and licensing: `inventory_items`, `package_activations`,
+  `freemius_plans`, `freemius_pricing`
+- Checkout and fulfillment: `orders`, `order_items`, `shipping_zones`,
+  `shipping_zone_locations`, `shipping_zone_methods`, `tax_rates`,
+  `currencies`
+
+`products` can be physical or digital. The current provider selection logic
+resolves:
+
+- physical -> Stripe
+- digital -> Freemius
+
+Mixed-provider carts are rejected by `app/api/checkout/route.ts`.
+
+## Multi-Currency
+
+The multi-currency implementation is real and fairly deep.
+
+### Store currencies
+
+`currencies` stores:
+
+- ISO code and symbol
+- exchange rate relative to the current store default
+- default and active flags
+- rounding mode, rounding increment, and optional charm ending
+- automatic FX refresh flag
+- automatic product price sync flag
+- last exchange-rate source and refresh timestamp
+
+Supported rounding modes in code are:
+
+- `none`
+- `nearest`
+- `up`
+- `down`
+- `charm`
+
+### Product and variant pricing
+
+Products and variants support:
+
+- legacy single-currency `price` and `sale_price`
+- multi-currency `prices` and `sale_prices`
+
+The pricing helpers resolve amounts by:
+
+1. looking for an explicit amount in the selected currency
+2. falling back to the base price
+3. converting from the default currency when store-managed auto-sync pricing is
+   enabled
+
+The CMS product editor respects that distinction. Store-managed currencies can
+be displayed in forms, but their saved overrides are stripped before
+persisting.
+
+### Scheduled sales, price changes, and promotions
+
+Products and variants carry a scheduled-pricing layer (migration
+`00000000000025_add_sale_schedule_columns.sql`):
+
+- `sale_start_at` / `sale_end_at` — the time window during which `sale_price` /
+  `sale_prices` apply. Both null = always-on (back-compat with static sales).
+- `scheduled_price` / `scheduled_prices` / `scheduled_price_at` — a pending,
+  permanent regular-price change applied once `scheduled_price_at` passes
+  (bulk/Stripe-oriented; Freemius regular prices are owned by Freemius).
+- `product_freemius_sale_coupons` — maps a product to an auto-generated,
+  time-bounded Freemius coupon so a scheduled Freemius sale is actually enforced
+  at Freemius-hosted checkout (Freemius enforces the coupon's start/end dates).
+
+**Enforcement is read-time, not cron-driven.** The helpers in
+`libs/ecommerce/src/lib/currency.ts` decide what applies *now*:
+
+- `isSaleWindowActive({ saleStartAt, saleEndAt, now })`
+- `resolveEffectivePriceForCurrency({ ..., saleStartAt, saleEndAt, scheduledPrice*, now })`
+  — wraps `resolvePriceForCurrency`, gating the sale by its window and swapping in
+  a due scheduled price. A sale outside its window resolves to `sale_price: null`.
+
+Every place that computes a payable or displayed amount goes through the
+window-aware helper: checkout providers (`providers/stripe.ts`,
+`providers/freemius.ts`), cart/tax/coupon math, and storefront components
+(`ProductCard`, `FeaturedProduct`, `ProductDetailsLayout`, UCP). The CMS edit
+form exposes the window per-product and per-variant (`SaleScheduleFields`); the
+bulk **Promotions** admin (`/cms/promotions`, `apps/nextblock/lib/promotions/`)
+imports/exports sales and price changes via CSV.
+
+> **Gotchas for future agents (these caused real revert/display bugs):**
+>
+> 1. **`generateVariantDrafts` (`variation-utils.ts`) must carry over every
+>    per-variant field**, including `sale_start_at`/`sale_end_at`. It re-runs on
+>    editor mount/attribute change; an omitted field resets to null and is then
+>    autosaved away ("dates revert after publish").
+> 2. **Storefront block mappers must pass the window through** on *both* the
+>    product and each variant — `ProductGridBlock`, `FeaturedProductBlock`,
+>    `app/product/[slug]/page.tsx`. If the window is dropped, `isSaleWindowActive`
+>    sees both bounds null and treats the sale as always-on, so an inactive sale
+>    price shows (e.g. a "$25 – $32" range before the sale starts).
+> 3. **`getVariantEffectivePriceRange` is window-aware** — pass
+>    `sale_start_at`/`sale_end_at` per variant or it ignores the schedule.
+> 4. **Persisting on save/publish does not rely on the RPC.** Products are
+>    written via `upsert_product_with_variants`, but some databases run a stale
+>    copy of that function. `persistProductSaleSchedule` (`product-actions.ts`)
+>    writes the window columns with a direct `update` right after the RPC (same
+>    pattern as `persistProductTaxability`), matching variants by SKU.
+> 5. **Autosave must not `reset()` the form or revalidate the edit route.** The
+>    edit-form autosave (`ProductForm.tsx`) uses a serialized-snapshot guard to
+>    avoid a render loop; `updateProductAction` writes only the draft (no
+>    `revalidatePath`). Re-rendering mid-edit resets native datetime inputs.
+
+### FX sync and rebasing
+
+`libs/ecommerce/src/lib/currency-sync.ts` implements two separate operations:
+
+- `syncStoreCurrencyRates()`: pulls fresh FX rates from `https://api.frankfurter.dev`
+  unless `FX_API_BASE_URL` overrides the provider.
+- `rebaseStoreCurrencyExchangeRates()`: when an admin changes the default
+  currency, every stored rate is rebased so the new default becomes `1`.
+
+The app exposes both through:
+
+- CMS currency settings actions in
+  `apps/nextblock/app/cms/settings/currencies/actions.ts`
+- `GET /api/cron/sync-currencies`, guarded by `CRON_SECRET`
+
+## Tax Calculation
+
+Tax behavior is driven by the `ecommerce_inventory_settings` site setting,
+loaded through `getEcommerceInventorySettings()`.
+
+The current settings shape is:
+
+- `trackQuantities`
+- `enableTaxes`
+- `taxCalculationMode`
+
+Supported tax modes are:
+
+- `manual`
+- `automatic`
+
+### Manual mode
+
+Manual mode uses `tax_rates` rows keyed by country and optional state/province.
+Multiple rows can exist for the same jurisdiction, so stacked taxes such as GST
+plus PST are supported.
+
+During checkout:
+
+- only taxable products are included
+- the destination is normalized from shipping or billing data
+- matching `tax_rates` are loaded
+- tax lines are calculated and stored in `orders.tax_details`
+
+### Automatic mode
+
+Automatic mode defers final tax calculation to Stripe Tax.
+
+In this mode:
+
+- checkout still records a tax intent in `orders.tax_details`
+- the Stripe provider marks product and shipping tax codes on line items
+- the webhook resync step replaces provisional tax data with finalized Stripe
+  checkout data
+
+## Shipping Zones and Rate Resolution
+
+Shipping is backed by:
+
+- `shipping_zones`
+- `shipping_zone_locations`
+- `shipping_zone_methods`
+
+Each method stores:
+
+- base amount and currency
+- localized names
+- per-currency amount maps and threshold maps
+- `currency_pricing_mode` of `auto` or `manual`
+
+### Current resolver behavior
+
+`libs/ecommerce/src/lib/shipping/resolver.ts` currently:
+
+1. loads active currencies
+2. queries zone locations by destination country
+3. prefers a state match when one exists
+4. otherwise prefers a country-wide match
+5. otherwise falls back to the first zone by `priority_order`
+6. filters methods by the cart total and minimum threshold
+7. converts method prices into the shopper currency
+8. returns only the cheapest valid method
+
+Important implementation detail: `shipping_zone_locations.postal_code` exists in
+schema, but the current resolver does not yet use postal code matching during
+runtime resolution.
+
+The storefront calls this through
+`libs/ecommerce/src/lib/server-actions/shipping-actions.ts`.
+
+## Stripe Integration
+
+Stripe is the current payment flow for physical products.
+
+### Checkout flow
+
+`app/api/checkout/route.ts`:
+
+- verifies the ecommerce package is active
+- rejects carts without provider-aware items
+- rejects mixed-provider carts
+- requires a billing address
+- resolves the provider through `getPaymentProvider()`
+
+`StripeProvider.createCheckoutSession()` then:
+
+- loads currencies and store settings
+- validates products and variants against the database
+- validates inventory before session creation when quantity tracking is enabled
+- resolves shipping cost from the selected shipping method
+- calculates tax in manual or automatic mode
+- upserts a Stripe customer when an email is available
+- inserts a pending `orders` row plus `order_items`
+- stores currency, subtotal, shipping, tax, and exchange-rate data
+- creates the Stripe Checkout Session and stores `stripe_session_id`
+
+### Webhook flow
+
+`app/api/webhooks/stripe/route.ts` passes the raw body to
+`handleStripeWebhook()`.
+
+On `checkout.session.completed`, the sync layer:
+
+- reloads the session with tax breakdown details
+- finds the existing order
+- stores payment intent, customer details, and finalized totals
+- normalizes tax details from Stripe
+- updates saved customer addresses
+- assigns invoice metadata
+- applies inventory deduction
+
+## Freemius Licensing and Product Sync
+
+Freemius currently handles digital-product checkout and product synchronization.
+
+### Checkout behavior
+
+`FreemiusProvider.createCheckoutSession()`:
+
+- only allows one item per checkout
+- loads the product from Supabase
+- requires `freemius_product_id` and `freemius_plan_id`
+- resolves pricing in the chosen currency
+- inserts a pending order and order item
+- optionally syncs default addresses and profile fields for the current user
+- builds a Freemius checkout URL, including sandbox parameters when enabled
+
+Supported credential sources include:
+
+- product-scoped JSON map
+- single-product sandbox overrides
+- single-product env vars
+- legacy shared env vars
+
+### Product sync
+
+`syncFreemiusProductsToSupabase()` and `syncSingleFreemiusProduct()`:
+
+- call the Freemius API with signed requests
+- fetch plugins, plans, and pricing
+- upsert digital products into `products`
+- upsert related `freemius_plans` and `freemius_pricing`
+
+These flows are surfaced in the CMS product actions and the sandbox reset route.
+
+### Current webhook limitation
+
+`app/api/webhooks/freemius/route.ts` currently verifies the webhook signature
+and acknowledges selected event types, but it does not yet reconcile license or
+order state back into the local database.
+
+## Inventory Management and Fulfillment
+
+Inventory behavior is controlled by `trackQuantities`.
+
+When tracking is enabled:
+
+- checkout validates requested quantity against `inventory_items`
+- if a SKU is not yet cached there, product or variant stock fields are used as
+  fallback
+- a paid order triggers `apply_order_inventory_deduction()`
+
+The deduction flow is resilient:
+
+- first it calls the database RPC `apply_order_inventory_deduction`
+- if that fails, it falls back to a direct SQL reconciliation path using
+  `POSTGRES_URL` or `DATABASE_URL`
+
+Order statuses currently supported in code are:
+
+- `pending`
+- `paid`
+- `shipped`
+- `cancelled`
+- `refunded`
+
+Manual CMS order status changes also trigger invoice assignment and inventory
+deduction when an order is moved to `paid`.
+
+## Invoice and Order Presentation
+
+The order/invoice layer includes:
+
+- stable invoice numbering through database functions
+- `invoice_settings` in `site_settings`
+- printable invoice presentation data via `invoice-server.ts`
+- UI components such as `InvoiceDocument` and `InvoiceViewerShell`
+- customer order history and invoice access through `customer-orders.ts`
+
+## CMS Commerce Surfaces
+
+The active ecommerce CMS surface includes:
+
+- product list, create, edit, media, attribute, and variation management
+- inventory management
+- orders list and detail management
+- shipping zones and shipping rate management
+- payment-provider enablement
+- tax settings and manual tax-rate management
+- currency settings under `/cms/settings/currencies`
+
+The CMS shell only exposes these store sections when the ecommerce package is
+reported as active.

package/templates/nextblock-template/docs/03-CMS-AND-EDITOR.md

@@ -0,0 +1,202 @@
+# 03 CMS and Editor
+
+## Two Related Systems
+
+NextBlock's content authoring experience is split across two real subsystems:
+
+- `libs/editor`: a reusable Tiptap-based rich text package
+- `apps/nextblock/lib/blocks`: the block registry and page-builder layer used
+  by pages, posts, and some commerce surfaces
+
+They work together, but they are not the same thing.
+
+## Block Registry and Page Builder
+
+The block registry lives in `apps/nextblock/lib/blocks/blockRegistry.ts`. It is
+the current source of truth for:
+
+- available block types
+- Zod schemas
+- default content
+- editor component filenames
+- renderer component filenames
+- human-facing labels and block metadata
+
+### Current registered block types
+
+The registry currently includes:
+
+- `text`
+- `heading`
+- `image`
+- `button`
+- `posts_grid`
+- `video_embed`
+- `section`
+- `form`
+- `testimonial`
+- `product_grid`
+- `featured_product`
+- `cart`
+- `checkout`
+- `product_details`
+
+The authoritative type list is `apps/nextblock/lib/blocks/blockTypes.ts`
+(`availableBlockTypes`).
+
+A `section` block can contain nested column block arrays, so the page builder
+supports multi-column compositions instead of only flat block lists. Legacy
+`hero` blocks were folded into `section` (carrying an `is_hero` flag) by
+migration `00000000000021_migrate_hero_blocks_to_sections.sql`, so `hero` is no
+longer a standalone registered block type.
+
+### How the CMS uses the registry
+
+The CMS block editor components under `app/cms/blocks` use the registry to:
+
+- validate block types
+- build new block payloads from default content
+- dynamically load editor components
+- dynamically load renderer components
+- render block labels and picker entries
+
+The registry also exposes helper functions such as:
+
+- `getBlockDefinition()`
+- `getInitialContent()`
+- `getBlockSchema()`
+- `validateBlockContent()`
+- `generateDefaultContent()`
+
+## Tiptap Editor Package
+
+The reusable editor surface lives in `libs/editor`.
+
+The main exports today are:
+
+- `Editor`
+- `NotionEditor`
+- `EditorToolbar`
+- `EditorBubbleMenu`
+- `EditorFloatingMenu`
+- `EnhancedFloatingMenu`
+- `SlashCommandList`
+- `DragHandle`
+- `HtmlContent`
+- `editorExtensions`
+
+### Core editing capabilities
+
+`libs/editor/src/lib/kit.ts` composes the editor from Tiptap extensions and
+custom nodes. The shipped editing surface includes:
+
+- StarterKit-based rich text
+- syntax-highlighted code blocks via `CodeBlockLowlight`
+- tables
+- task lists
+- link handling
+- text styling through `TextStyleKit`
+- highlight, subscript, superscript, and typography helpers
+- character counting
+- slash commands
+- drag handles and draggable node movement
+- image handling
+
+### Custom HTML-preserving extensions
+
+The editor intentionally preserves more HTML than a minimal rich text field.
+Current custom nodes/extensions include support for:
+
+- `div`
+- `style`
+- `script`
+- `svg`
+- `span`
+- a catch-all attribute preservation layer
+
+This matters because some CMS-authored content and seeded content store richer
+HTML fragments than plain paragraph markup.
+
+## Inline Widgets
+
+The editor currently ships two inline widget node types:
+
+- alert widget
+- call-to-action widget
+
+These appear in multiple places:
+
+- Tiptap commands and slash-command actions
+- editor node views in `libs/editor`
+- runtime React renderers in `apps/nextblock/components/blocks/renderers/inline`
+
+So the widgets are not just editor-only decorations; they have both editing and
+front-end rendering paths.
+
+## NotionEditor Integration Pattern
+
+`NotionEditor` is the higher-level client component used by the app. It wraps:
+
+- the extension kit
+- toolbars and menus
+- content synchronization through `onChange` and `onUpdate`
+- media picker bridging through editor storage
+- hydration-safe initialization with `immediatelyRender: false`
+- a scrollable editing shell and character counts
+
+The app currently mounts it in multiple places, including:
+
+- text block editing
+- product description editing
+
+## Media Picker Integration
+
+The editor integrates with a pluggable image picker bridge:
+
+- `setOpenImagePicker()` stores a picker callback on the editor instance
+- menus and extensions can open the media picker without knowing app details
+- the CMS supplies the actual picker UI
+
+This keeps the editor package reusable while still supporting CMS media
+selection.
+
+## Commerce-Aware Blocks
+
+The block layer is not content-only. The app also ships block types that render
+commerce primitives backed by `@nextblock-cms/ecommerce`, including:
+
+- product grid
+- featured product
+- cart
+- checkout
+- product details
+
+These bridge the CMS page builder to the premium commerce library without
+copying storefront logic into the app.
+
+## Custom Blocks (Data-Driven CRUD)
+
+Beyond the code-defined built-ins above, editors can create their own block
+types at runtime from the CMS, with no code deploy. These **custom block
+definitions** are stored as rows in `custom_block_definitions` (typed fields
+plus a recursive layout schema) and rendered on the public site by a dynamic
+layout engine instead of a compiled React renderer.
+
+The wiring is intentionally simple: a page/post block whose `block_type` equals
+a custom definition's `slug` is resolved through
+`getCachedCustomBlockDefinitionBySlug()` and rendered by
+`CachedDynamicLayoutEngine`. Authoring, CRUD, duplicate, and JSON
+import/export/backup all live under `app/cms/custom-blocks`.
+
+Full details, including the field types, the layout schema, caching, and the
+Cortex AI "build widget" path, are in
+[10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md).
+
+## Relationship to the SDK
+
+The registry is the current in-app block system. The formal external authoring
+contract lives in `libs/sdk` and is documented in
+[07-BLOCK-SDK-AND-EXTENSIBILITY.md](./07-BLOCK-SDK-AND-EXTENSIBILITY.md).
+
+If you are changing how blocks work inside the CMS, start here. If you are
+designing a reusable third-party block contract, start with the SDK doc.