Shopping List - SpurtCommerce

The Shopping List (Shopping Cart) add-on extends Picco360 / SpurtCommerce with customer-managed shopping lists and vendor-assisted cart management. Customers can create lists and manage products/SKU variants. Vendors can view customer lists, add products on a buyer’s behalf, duplicate lists, record order conversions, and review dashboard analytics.

Naming: The source module is named ShoppingCart. The user-facing feature is referred to as Shopping List / Shopping Cart. This guide retains the source names for code, database tables, and API routes.

Features

Storefront customers

Create, rename, view, and delete shopping-list groups.
Add, update, and remove product/SKU line items.
View list subtotal and item count.
Retrieve enriched item details, including product, SKU, pricing, discount/special pricing, and stock status.
Use a lightweight list endpoint for dropdowns and SKU-in-list indicators.

Vendors

View customer shopping lists with filters.
Add products to a customer’s list, subject to tenant, stock, and quantity validation.
Duplicate a list for a customer.
View list details and products.
Mark a list as ordered for conversion tracking.

Vendor analytics

Repeated products and repeat customers.
New-list and order-conversion counts.
Total revenue from ordered lists.
Date-grouped list and new-customer charts.
Trending products based on ordered lists.

Architecture

The add-on uses a layered architecture integrated with the platform’s routing, dependency injection, ORM, and event-hook infrastructure.

HTTP request
    |
Tenant / authentication middleware
    |
Controller -> DTO validation -> Service -> Repository -> TypeORM -> Database
                                  ^
                                  |
Platform events <---- ShoppingCartHook

Layer Responsibility

Controllers Store and vendor HTTP endpoints using routing-controllers. Request DTOs Validate payloads with class-validator and class-transformer. Services Business logic and coordination through typedi. Repositories TypeORM access and custom reporting queries. Models Entities mapped to shopping_cart and shopping_cart_detail. Migrations Schema changes, plugin registration, and permission seeding.

Hook Connects order-placement and customer-deletion events through `HookUtil`.

Technology stack

Area Technology

Language / runtime TypeScript / Node.js Routing routing-controllers Dependency injection typedi ORM TypeORM Validation class-validator, class-transformer Database MySQL / MariaDB Dates moment.js Metadata reflect-metadata Platform integration HookUtil, getDataSource The supplied README does not state exact dependency version constraints. Confirm compatibility against the target SpurtCommerce/Picco360 application’s package configuration.

Directory structure

ShoppingCart/
├── ShoppingCartHook.ts
├── controllers/
│   ├── store/
│   │   ├── StoreShoppingCartController.ts
│   │   ├── StoreShoppingCartDetailController.ts
│   │   └── requests/
│   └── vendor/
│       ├── VendorShoppingCartController.ts
│       ├── VendorShoppingCartDashboardController.ts
│       └── requests/
├── models/
│   ├── ShoppingCart.ts
│   └── ShoppingCartDetail.ts
├── repositories/
│   ├── ShoppingCartRepository.ts
│   └── ShoppingCartDetailRepository.ts
├── services/
│   ├── ShoppingCartService.ts
│   └── ShoppingCartDetailService.ts
└── migrations/
    ├── 1747200087804-ShoppingCartPluginSeed.ts
    ├── 1747200372449-CreateShoppingCartTable.ts
    ├── 1747200938997-CreateShoppingCartDetailTable.ts
    ├── 1748514150206-AlterShoppingCartPluginSeed.ts
    ├── 1749279888714-AddCollumnIsOrdered.ts
    ├── 1750051962853-UpdatePluginRoutingUrl.ts
    ├── 1750066197446-AddCollumnShoppingCart.ts
    ├── 1751352779017-UpdatePluginRouteUrl.ts
    └── 1752584905864-AddVendorPermissionShoppingCart.ts

Main components

Component Responsibility

StoreShoppingCartController Storefront list-group operations. StoreShoppingCartDetailController Storefront line-item operations. VendorShoppingCartController Vendor list management, duplication, and order status. VendorShoppingCartDashboardController Vendor analytics endpoints. ShoppingCartService Shopping-list group business logic and query-builder listing. ShoppingCartDetailService Line-item business logic. ShoppingCartRepository Custom reports: repeated products/customers, revenue, and charts.

`ShoppingCartDetailRepository` Line-item repository wrapper.

Data model

The add-on has two primary entities with a one-to-many relationship:

ShoppingCart (1) -------- (N) ShoppingCartDetail

`ShoppingCart` --- `shopping_cart`

Represents a shopping-list group owned by a customer within a tenant.

Field Description

id Primary key. customer_id Owning customer. name Shopping-list name. is_default Default-list flag. is_active Active flag. is_delete Soft-delete flag. tenant_id Tenant/vendor scope. created_by, modified_by Creator and last modifier user IDs. created_date, modified_date Creation and modification timestamps. is_ordered Whether the list has been ordered (0 / 1). customer_user_id Customer user ID. created_by_type Creator type: seller or buyer.

`notes` List notes.

When a customer creates a new default list, an existing default list is first changed to non-default.

`ShoppingCartDetail` --- `shopping_cart_detail`

Stores line items inside a list.

Field Description

id Primary key. product_id Product ID. shopping_cart_id Parent list ID; foreign key to shopping_cart.id. sku_id Selected SKU ID. variant_option_id Variant option ID. variant_option_name Variant option name. quantity Quantity; default 1. price Unit price; decimal(10,2), default 0.00. notes Item notes. is_active, is_delete Active and soft-delete flags.

Audit fields `created_by`, `modified_by`, `created_date`, `modified_date`.

The detail table’s foreign key cascades when its parent cart record is deleted.

Storefront workflow and API

The storefront endpoints allow customers to manage their own shopping-list groups and line items.

Create a list --- POST /api/store-shopping-cart. Uses create-shopping-list; a new list is marked as created by a buyer. If it becomes the default list, the existing default is unset.
Add or update items --- POST /api/store-shopping-cart-detail. Validates product/SKU, minimum and maximum quantity, and stock. If the same product + SKU already exists, its quantity is incremented.
List groups --- GET /api/store-shopping-cart. Returns lists with subtotal and item count.
Dropdown data --- GET /api/store-shopping-cart/list. Returns lightweight list data and indicates whether a SKU is already in a list.
List detail --- GET /api/store-shopping-cart/:id/detail. Returns line items enriched with product, SKU, pricing/discount, and stock information.
Update a group --- PUT /api/store-shopping-cart/:id.
Delete a group --- DELETE /api/store-shopping-cart/:id.
Remove line items --- POST /api/store-shopping-cart-detail/delete.

Method Endpoint Permission Description

POST /api/store-shopping-cart customer, create-shopping-list Create a list group. PUT /api/store-shopping-cart/:id customer, create-shopping-list Update a list group. GET /api/store-shopping-cart/list customer, view-shopping-list Lightweight dropdown list. GET /api/store-shopping-cart customer, view-shopping-list Customer list groups. GET /api/store-shopping-cart/:id/detail customer, List line-item view-shopping-list-line-item details. DELETE /api/store-shopping-cart/:id customer, delete-shopping-list Delete a list group. POST /api/store-shopping-cart-detail customer, Add/update line edit-shopping-list-line-item items.

`POST` `/api/store-shopping-cart-detail/delete` `customer`, Remove line `delete-shopping-list-line-item` items.

Vendor workflow and API

Vendor operations are scoped to the vendor’s tenant.

List customer lists --- GET /api/vendor-shopping-cart. Aggregates subtotal and item count, joins customer name, and supports customer, name, ordered-status, keyword, and date filters.
Add an item --- POST /api/vendor-shopping-cart. Validates tenant ownership, stock, and quantity limits; inserts or increments the line item and sends a customer notification using email template ID 60.
Duplicate a list --- POST /api/vendor-shopping-cart/create-duplicate. Creates a new default list from an item list, validates product/SKU tenant ownership, and emails the customer.
View list detail --- GET /api/vendor-shopping-cart/:id/detail.
View products --- GET /api/vendor-shopping-cart/:id/product-list.
Remove line items --- POST /api/vendor-shopping-cart/delete.
Mark as ordered --- PUT /api/vendor-shopping-cart/:id, setting is_ordered = 1.

Method Endpoint Permission Description

GET /api/vendor-shopping-cart vendor, List customer list-shopping-list shopping lists. POST /api/vendor-shopping-cart vendor, Add an item to a edit-shopping-list customer’s list; send notification. POST /api/vendor-shopping-cart/create-duplicate vendor, Duplicate a list duplicate-shopping-list for a buyer; send notification. GET /api/vendor-shopping-cart/:id/detail vendor, Retrieve list list-shopping-list details. GET /api/vendor-shopping-cart/:id/product-list vendor, Retrieve list list-shopping-list products. POST /api/vendor-shopping-cart/delete Not specified in README Remove line items.

`PUT` `/api/vendor-shopping-cart/:id` `vendor`, Update ordered `edit-shopping-list` status.

Vendor dashboard API

All dashboard endpoints are under /api/vendor-dashboard-shopping-cart and are described as vendor-role endpoints.

Method Endpoint Description

GET /api/vendor-dashboard-shopping-cart/reports/repeated-products Products appearing in more than one list. GET /api/vendor-dashboard-shopping-cart/reports/repeated-customers Customers with at least one ordered list and at least two lists overall. GET /api/vendor-dashboard-shopping-cart/new Count of new, not-ordered lists. GET /api/vendor-dashboard-shopping-cart/orders/conversions Count of ordered lists. GET /api/vendor-dashboard-shopping-cart/revenue/total Revenue from ordered lists. GET /api/vendor-dashboard-shopping-cart/chart-data List counts grouped by date (week/month/year). GET /api/vendor-dashboard-shopping-cart/customers/new New-customer chart data. The README does not provide report query parameters or detailed response schemas. Check VendorShoppingCartDashboardController and ShoppingCartRepository for those definitions.

Response format

The supplied README describes the platform response envelope as:

{
  "status": 1,
  "message": "Success message",
  "data": {}
}

status is documented as 1 or 0. The exact message and data structure varies by endpoint. The source README does not include exact request DTOs or endpoint-level JSON examples; consult the relevant controller and request DTO before implementing a client.

Hooks and cross-module integration

ShoppingCartHook.ts self-registers with the platform’s central HookUtil. It exposes repository-safe operations such as save, find, find-one, update, and delete-shopping-cart. Repository access is guarded so the hook can be called before the TypeORM DataSource is initialized or before the ShoppingCart entity is registered.

Event Handler Behavior

shopping_cart_order handleOrder Marks the referenced list isOrdered = 1 when an order is placed. shopping_list_order handleOrder Alias for the order event. shopping_cart_customer_delete handleCustomerDelete Soft-deletes lists belonging to a deleted customer user.

`shopping_list_customer_delete` `handleCustomerDelete` Alias for the customer-deletion event.

The README does not specify the exact event payload. Inspect the hook implementation and platform event callers before emitting these events from another module.

Permissions

Migration 1752584905864-AddVendorPermissionShoppingCart.ts seeds the Shopping List permission group (slug_name = shopping-list, sort order 32).

Vendor permissions

Slug Name Listed

list-shopping-list List Shopping List Yes edit-shopping-list Edit Shopping List No duplicate-shopping-list Duplicate Shopping List No

Storefront permissions

The store controllers reference these customer permissions:

create-shopping-list
view-shopping-list
view-shopping-list-line-item
delete-shopping-list
edit-shopping-list-line-item
delete-shopping-list-line-item

Assign the relevant permissions to the appropriate customer and vendor roles in the host application.

Database migrations

Run migrations in timestamp order using the platform’s TypeORM migration runner.

Order Migration Purpose

1 1747200087804-ShoppingCartPluginSeed.ts Registers the ShoppingCart plugin (Sales type; initial vendor route). 2 1747200372449-CreateShoppingCartTable.ts Creates shopping_cart. 3 1747200938997-CreateShoppingCartDetailTable.ts Creates shopping_cart_detail and its cascading foreign key. 4 1748514150206-AlterShoppingCartPluginSeed.ts Updates/upserts the plugin record. 5 1749279888714-AddCollumnIsOrdered.ts Adds is_ordered. 6 1750051962853-UpdatePluginRoutingUrl.ts Updates vendor and dashboard plugin routes. 7 1750066197446-AddCollumnShoppingCart.ts Adds customer_user_id, created_by_type, and notes. 8 1751352779017-UpdatePluginRouteUrl.ts Adds store routes and create-duplicate route metadata.

9 `1752584905864-AddVendorPermissionShoppingCart.ts` Seeds the Shopping List vendor permission group and permissions.

Production caution: The supplied README says every migration down() method is a no-op and describes the migrations as forward-only. Back up the database and review migration behavior before applying them. Do not assume that a normal migration rollback will reverse these changes.

Installation and setup

The supplied README documents source-directory installation, not an npm package installation. It does not specify a package name, npm install command, or programmatic initialization function.

1. Add the source directory

Copy the complete ShoppingCart/ directory into the add-ons location used by your Picco360 / SpurtCommerce project. Preserve its directory structure.

2. Register the entities

Ensure the host application’s TypeORM configuration registers:

ShoppingCart
ShoppingCartDetail

The README does not provide a ready-made entity array or host configuration snippet. Use the entity classes in models/ and follow the registration convention for your platform version.

3. Run the migrations

Run all nine migrations in the order shown above. Confirm that both tables, plugin metadata, route metadata, and permissions are present.

4. Register the hook

Ensure ShoppingCartHook.ts is loaded during application bootstrap so it can register with HookUtil. Confirm that order-placement and customer-deletion flows invoke the expected event names.

5. Enable controllers and permissions

The README states that controllers are discovered automatically by the platform’s routing-controllers setup and do not require manual route registration. Verify that the host application’s controller discovery includes the add-on’s store and vendor controller directories. Assign the vendor and storefront permissions to the appropriate roles.

6. Verify the integration

Test in a development or staging environment before production:

Application starts with both entities registered.
All migrations complete successfully.
Customers can create, view, update, and delete lists.
Customers can add, update, and remove line items.
Product/SKU, stock, and min/max quantity validation works.
Vendors can view lists and add products within their tenant.
Duplicate-list creation works and sends the expected notification.
Marking a list as ordered updates is_ordered.
Order and customer-deletion hooks execute correctly.
Dashboard reports return expected data for test records.

Operational considerations

Tenant isolation: Preserve vendor tenant checks for lists, products, and SKUs.
Inventory validation: Keep stock and min/max quantity checks when extending line-item operations.
Email notifications: Vendor add-item and duplicate-list flows use email template ID 60. Verify that the template and mail service are configured.
Soft deletion: The entities use is_delete; customer deletion is handled through a soft-delete hook.
Order conversion: is_ordered records conversion, and the order hook updates it.
Forward-only migrations: Back up the database and plan manual recovery before applying migrations to production.

Troubleshooting

Issue Checks

Store/vendor routes are missing Check controller discovery and confirm plugin route migrations have run. Database or table errors Confirm both entities are registered and migrations ran in timestamp order. Vendor cannot access a list Check tenant ownership and the relevant vendor permission. Customer receives an authorization Check the customer’s storefront error shopping-list permissions. Customer does not receive a Verify mail configuration and email notification template ID 60. List is not marked ordered Verify the order flow emits shopping_cart_order or shopping_list_order with the payload expected by the hook.

Dashboard report is empty Check test data, `is_ordered`, and the report query filters.

Source files for deeper implementation details

For exact DTO fields, event payloads, and report query parameters not present in the README, inspect:

controllers/store/StoreShoppingCartController.ts
controllers/store/StoreShoppingCartDetailController.ts
controllers/vendor/VendorShoppingCartController.ts
controllers/vendor/VendorShoppingCartDashboardController.ts
controllers/store/requests/
controllers/vendor/requests/
models/ShoppingCart.ts
models/ShoppingCartDetail.ts
ShoppingCartHook.ts
repositories/ShoppingCartRepository.ts
services/ShoppingCartService.ts
services/ShoppingCartDetailService.ts

License

The supplied README does not specify the add-on’s license. Check the source repository’s license file before redistribution or modification.