@aglyn/plugins-commerce

The Commerce plugin for Aglyn: products, carts, checkout, orders and point of sale, plus the visitor accounts and member blocks that ship in the same bundle. Install it if you are running or building on the Aglyn platform and want a storefront.

Published to npm from the Aglyn monorepo. Versions follow semantic versioning.

Install

npm install @aglyn/plugins-commerce

Peer dependencies:

• @mui/material
• firebase
• next
• react

None is optional. The server half additionally relies on firebase-admin through @aglyn/tenant-data-admin.

What's in it

This package is a first-party Aglyn plugin. It is loaded through Aglyn's plugin manager: the apps read its entry in the monorepo's plugins.config.json, import the module each surface names, and call the registrar declared for that surface. It is not a standalone library; installing it on its own loads nothing.

On a published site

registerCommercePlugin() registers these canvas components, placed in Besigner like any other element:

• Storefront: product-grid, product-detail, related-products, product-reviews, cart, wishlist, reservation-widget, newsletter-signup
• Accounts and members: customer-account, member-signin, member-signup, member-recovery, member-feed, gate, gated-video

Component ids are persisted in screen documents and are never renamed.

The entry in plugins.config.json also declares an accounts capability ("User Accounts"): visitor accounts on the site, with the sign-in, sign-up and recovery pages and the member blocks. It requires commerce, is off for a site until turned on, and has no separate package; this bundle registers its blocks and its membership/* handlers.

In the console

registerCommerceConsole() registers:

• A Products nav item and page at /products, with the sections Catalog, Orders, Promotions, Reservations, Settings and Analytics as routes.
• A POS nav item and page at /pos, which requires the plugin's own managePos permission.
• A "Commerce" widget in the commerceGlance slot, and a "Newest site users" widget in the hostDashboard slot under the accounts capability.
• A "Purchases" widget in the siteMember slot: a site user's lifetime purchase total, orders and subscriptions, in their drawer on the site's Users page.
• The plugin's permissions (COMMERCE_PERMISSIONS) and its config schema (COMMERCE_CONFIG_SCHEMA, which holds the POS discount ceiling).
• Widgets in other plugins' zones (AGL-4098): "Start a quote" on a quote request in the Inbox (inboxSubmissionActions) and on a contact in the CRM (crmRecordActions), each opening the quote editor filled in.
• The product-options-field element (AGL-4098): a form field for a product and its options, which posts its readable line under its name and the exact choice under {name}__data.
• Three zones its own surfaces host, declared with registerPluginZone: productEditor (among the product editor's fields), productsHub (above the catalog table) and productImport (the products import wizard's After import step). Their props are declared on the zone tokens in components/console/product-zones.
• The client halves of its six import and export resources, the products wizard's After import step and the gift card import's Confirm step (transfer/register-transfer-ui). The products, orders, discounts, coupons, gift cards and categories cards open the console's import wizard and export dialog through the core launcher (useTransferLauncher).

All console pages and cards are code-split.

Starter sites

commerceStarterTemplates() (starter-templates) returns the two shop starters, "Shop (physical products)" and "Shop (digital products)": home, shop, product page, cart and account pages built around this plugin's elements. plugins.config.json names it under starterTemplates, and the manifest generator compiles the starters into core's STARTER_TEMPLATES, which the template gallery, the seed route and the AI plugin's examples read. The starter ids, page keys and node ids are persisted in every site that used one.

On the server

@aglyn/plugins-commerce/server pulls in firebase-admin and Stripe and is kept out of the client entry point.

• registerCommerceApi() (the tenantApi surface) registers the storefront routes under commerce/ (catalog, product, related, reviews, cart, cart checkout, checkout, download, feed, newsletter, restock notifications, order analytics, order status, the customer's quote page, its Pay button and its PDF (quote-view, quote-pay, quote-pdf), its proofs, the customer's artwork upload and their answer (quote-proof, quote-upload, quote-respond), and their messages to the business (quote-message); the same page, Pay button and PDF serve an invoiced draft order's lasting pay link, reservations, gate, member feed, stream, subscription portal) and the account routes under membership/ (register, login, logout, recover, reset, account, content, wishlist). It also registers a site page resolver and enricher, the commerce tax profile and a product card reader on core seams.

• registerCommerceConsoleApi() (the consoleApi surface) registers the merchant routes: cancel, fulfill and refund an order, draft orders, quotes with their pay links, PDFs, proofs, revisions and the email that sends them (quote send), an order's or a quote's invoice email (order-invoice-send), and a quote started from a form's quote request (quote start-from-request, and create with from, read through the forms plugin's forms.submission facts), POS orders, gift cards, member posts, a site member's password help and removal (membership/admin-password, membership/admin-remove), Stripe Connect, supplier updates, and the abandoned-checkout and restock processors. It also adds a handler on the platform billing webhook and order figure readers.

• registerCommerceConsoleApi() also registers what an AI build may make in a store, on core's resource-drafts and AI-capability seams: the product draft writer and build op, and the store-settings writer with the store-shipping, store-pickup, store-delivery and store-tax build ops (server/store-setup-ai-*.ts). Those four set shipping zones and rates, pickup, local delivery and sales tax exactly as the console's cards save them, live, using only amounts and rates the request states, and never a carrier or tax-service account. model/store-setup-content.ts holds the pure read-and-apply step.

• Loading the module registers scheduled plugin jobs: abandoned-checkout-recovery, back-in-stock-alerts, review-request-emails, stock-decrement-reconciliation, supplier-webhook-delivery, payment-method-domains and pos-reader-splash-refresh (card reader start-up screens after a logo change). This is why package.json lists ./src/lib/server.* under sideEffects.

• registerCommerceConsoleServerDeclarations() (the consoleServerDeclarations surface) declares commerce-quote-upload-sweep, a console job on the same fifteen-minute tick as the forms plugin's sweep, that deletes the artwork a customer attached to an answer on a quote and never sent, a day after its last upload (AGL-4096). Each file is recorded as pending at orders/{quoteId}/quoteUploadKeys/{quoteId} from its ticket until quote-respond sends it (server/quote-upload-keys.ts, server/quote-upload-sweep.ts).

• Product reviews are verified-buyer by default. commerce/reviews (POST) marks a review verified only for a signed-in site member whose proven email has an order that still entitles the product, or for a single-use link from the review-request email (server/review-tokens.ts: hashed, 60 days, bound to order, product and email). A typed email never verifies. Verified reviews publish at once; under the store's anyone policy (settings/store.reviews.policy) the rest wait as pending, and under verified they get 403. GET commerce/reviews?mode=eligibility tells the storefront block which form to draw. The POST is rate limited per address and per member. The order.fulfilled, order.delivered and order.paid subscriber stamps an order for its review request, and the hourly review-request-emails job sends it (server/review-requests.ts, catalog key review-request). Merchants hide a review only for a content reason (REVIEW_MODERATION_REASONS), which the Firestore rules enforce.

Routes are served by the host app's API dispatcher under /api/, for example /api/commerce/catalog.

Entry points

Usage

The registrars are normally called by Aglyn's generated plugin loaders. Called directly:

// Published site (canvas half only)
import { registerCommercePlugin } from '@aglyn/plugins-commerce/site'
registerCommercePlugin()

// Console app
import { registerCommerceConsole } from '@aglyn/plugins-commerce'
registerCommerceConsole()

// Server-only API dispatcher
import {
  registerCommerceApi,
  registerCommerceConsoleApi,
} from '@aglyn/plugins-commerce/server'
registerCommerceApi()

How it fits

A plugin may import the tenant runtime, the renderer, the Besigner logic, the core and the shared packages. It never imports another plugin, and the core never imports a plugin. Commerce depends on @aglyn/aglyn, @aglyn/tenant-runtime, @aglyn/tenant-data-admin, @aglyn/tenant-feature-instance, several @aglyn/shared-* packages, and the Stripe client libraries. What other plugins need from it goes through core seams: it registers the plugin tax profile that a paid booking is priced with, and the product card and order figure readers other plugins read by contract.

License

Apache-2.0. Source: https://github.com/aglyn/aglyn/tree/main/libs/plugins/commerce