@marianmeres/ecsuite 1.0.0

package/dist/suite.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @module suite
+ *
+ * ECSuite - Main orchestrator for e-commerce frontend state management.
+ * Coordinates all domain managers, provides shared event system, and manages context.
+ */
+import { type Subscriber, type Unsubscriber } from "@marianmeres/pubsub";
+import type { CartAdapter, CustomerAdapter, OrderAdapter, PaymentAdapter, ProductAdapter, WishlistAdapter } from "./types/adapter.js";
+import type { DomainContext } from "./types/state.js";
+import type { ECSuiteEventType, ECSuiteEvent } from "./types/events.js";
+import { CartManager } from "./domains/cart.js";
+import { WishlistManager } from "./domains/wishlist.js";
+import { OrderManager } from "./domains/order.js";
+import { CustomerManager } from "./domains/customer.js";
+import { PaymentManager } from "./domains/payment.js";
+import { ProductManager } from "./domains/product.js";
+import type { StorageType } from "./domains/base.js";
+/** Configuration for ECSuite */
+export interface ECSuiteConfig {
+    /** Initial context (customerId, sessionId) */
+    context?: DomainContext;
+    /** Adapters for server communication */
+    adapters?: {
+        cart?: CartAdapter;
+        wishlist?: WishlistAdapter;
+        order?: OrderAdapter;
+        customer?: CustomerAdapter;
+        payment?: PaymentAdapter;
+        product?: ProductAdapter;
+    };
+    /** Storage configuration */
+    storage?: {
+        /** Cart storage key (default: "ecsuite:cart") */
+        cartKey?: string;
+        /** Wishlist storage key (default: "ecsuite:wishlist") */
+        wishlistKey?: string;
+        /** Storage type for persisted domains (default: "local") */
+        type?: StorageType;
+    };
+    /** Product cache TTL in milliseconds (default: 5 minutes) */
+    productCacheTtl?: number;
+    /** Auto-initialize on creation (default: true) */
+    autoInitialize?: boolean;
+}
+/**
+ * Main ECSuite class - orchestrates all e-commerce domain managers.
+ *
+ * Provides unified access to cart, wishlist, order, customer, payment, and product domains
+ * with shared event system and context management.
+ *
+ * @example
+ * ```typescript
+ * const suite = createECSuite({
+ *   context: { customerId: "user-123" },
+ *   adapters: { cart: myCartAdapter },
+ * });
+ *
+ * suite.cart.subscribe((state) => console.log(state));
+ * await suite.cart.addItem({ product_id: "prod-1", quantity: 1 });
+ * ```
+ */
+export declare class ECSuite {
+    private readonly _clog;
+    private readonly _pubsub;
+    private _context;
+    /** Cart domain manager */
+    readonly cart: CartManager;
+    /** Wishlist domain manager */
+    readonly wishlist: WishlistManager;
+    /** Order domain manager */
+    readonly order: OrderManager;
+    /** Customer domain manager */
+    readonly customer: CustomerManager;
+    /** Payment domain manager */
+    readonly payment: PaymentManager;
+    /** Product domain manager (read-only with caching) */
+    readonly product: ProductManager;
+    constructor(config?: ECSuiteConfig);
+    /** Initialize all domains */
+    initialize(): Promise<void>;
+    /** Update context across all domains */
+    setContext(context: DomainContext): void;
+    /** Get the current context */
+    getContext(): DomainContext;
+    /** Subscribe to specific event type */
+    on(eventType: ECSuiteEventType, callback: Subscriber): Unsubscriber;
+    /** Subscribe to all events (receives { event, data } envelope) */
+    onAny(callback: (envelope: {
+        event: string;
+        data: ECSuiteEvent;
+    }) => void): Unsubscriber;
+    /** Subscribe once to an event */
+    once(eventType: ECSuiteEventType, callback: Subscriber): Unsubscriber;
+    /** Reset all domains to initial state */
+    reset(): void;
+}
+/**
+ * Factory function to create an ECSuite instance.
+ *
+ * @param config - Optional configuration for the suite
+ * @returns A new ECSuite instance
+ *
+ * @example
+ * ```typescript
+ * const suite = createECSuite({
+ *   context: { customerId: "user-123" },
+ *   adapters: {
+ *     cart: myCartAdapter,
+ *     wishlist: myWishlistAdapter,
+ *   },
+ *   storage: { type: "local" },
+ * });
+ * ```
+ */
+export declare function createECSuite(config?: ECSuiteConfig): ECSuite;

package/dist/suite.js

@@ -0,0 +1,168 @@
+/**
+ * @module suite
+ *
+ * ECSuite - Main orchestrator for e-commerce frontend state management.
+ * Coordinates all domain managers, provides shared event system, and manages context.
+ */
+import { createClog } from "@marianmeres/clog";
+import { createPubSub } from "@marianmeres/pubsub";
+import { CartManager } from "./domains/cart.js";
+import { WishlistManager } from "./domains/wishlist.js";
+import { OrderManager } from "./domains/order.js";
+import { CustomerManager } from "./domains/customer.js";
+import { PaymentManager } from "./domains/payment.js";
+import { ProductManager } from "./domains/product.js";
+/**
+ * Main ECSuite class - orchestrates all e-commerce domain managers.
+ *
+ * Provides unified access to cart, wishlist, order, customer, payment, and product domains
+ * with shared event system and context management.
+ *
+ * @example
+ * ```typescript
+ * const suite = createECSuite({
+ *   context: { customerId: "user-123" },
+ *   adapters: { cart: myCartAdapter },
+ * });
+ *
+ * suite.cart.subscribe((state) => console.log(state));
+ * await suite.cart.addItem({ product_id: "prod-1", quantity: 1 });
+ * ```
+ */
+export class ECSuite {
+    _clog = createClog("ecsuite", { color: "auto" });
+    _pubsub;
+    _context;
+    /** Cart domain manager */
+    cart;
+    /** Wishlist domain manager */
+    wishlist;
+    /** Order domain manager */
+    order;
+    /** Customer domain manager */
+    customer;
+    /** Payment domain manager */
+    payment;
+    /** Product domain manager (read-only with caching) */
+    product;
+    constructor(config = {}) {
+        this._clog.debug("creating suite", {
+            hasAdapters: !!config.adapters,
+            autoInitialize: config.autoInitialize !== false,
+        });
+        this._pubsub = createPubSub();
+        this._context = config.context ?? {};
+        const storageType = config.storage?.type ?? "local";
+        // Initialize domain managers with shared pubsub
+        this.cart = new CartManager({
+            adapter: config.adapters?.cart,
+            context: this._context,
+            pubsub: this._pubsub,
+            storageKey: config.storage?.cartKey ?? "ecsuite:cart",
+            storageType,
+        });
+        this.wishlist = new WishlistManager({
+            adapter: config.adapters?.wishlist,
+            context: this._context,
+            pubsub: this._pubsub,
+            storageKey: config.storage?.wishlistKey ?? "ecsuite:wishlist",
+            storageType,
+        });
+        this.order = new OrderManager({
+            adapter: config.adapters?.order,
+            context: this._context,
+            pubsub: this._pubsub,
+        });
+        this.customer = new CustomerManager({
+            adapter: config.adapters?.customer,
+            context: this._context,
+            pubsub: this._pubsub,
+        });
+        this.payment = new PaymentManager({
+            adapter: config.adapters?.payment,
+            context: this._context,
+            pubsub: this._pubsub,
+        });
+        this.product = new ProductManager({
+            adapter: config.adapters?.product,
+            context: this._context,
+            pubsub: this._pubsub,
+            cacheTtl: config.productCacheTtl,
+        });
+        // Auto-initialize if configured
+        if (config.autoInitialize !== false) {
+            this.initialize();
+        }
+    }
+    /** Initialize all domains */
+    async initialize() {
+        this._clog.debug("initializing all domains");
+        await Promise.all([
+            this.cart.initialize(),
+            this.wishlist.initialize(),
+            this.order.initialize(),
+            this.customer.initialize(),
+            this.payment.initialize(),
+            // Note: ProductManager doesn't have initialize() - it's lazy-loaded
+        ]);
+        this._clog.debug("all domains initialized");
+    }
+    /** Update context across all domains */
+    setContext(context) {
+        this._clog.debug("setContext", context);
+        this._context = { ...this._context, ...context };
+        this.cart.setContext(context);
+        this.wishlist.setContext(context);
+        this.order.setContext(context);
+        this.customer.setContext(context);
+        this.payment.setContext(context);
+        this.product.setContext(context);
+    }
+    /** Get the current context */
+    getContext() {
+        return { ...this._context };
+    }
+    /** Subscribe to specific event type */
+    on(eventType, callback) {
+        return this._pubsub.subscribe(eventType, callback);
+    }
+    /** Subscribe to all events (receives { event, data } envelope) */
+    onAny(callback) {
+        return this._pubsub.subscribe("*", callback);
+    }
+    /** Subscribe once to an event */
+    once(eventType, callback) {
+        return this._pubsub.subscribeOnce(eventType, callback);
+    }
+    /** Reset all domains to initial state */
+    reset() {
+        this._clog.debug("reset all domains");
+        this.cart.reset();
+        this.wishlist.reset();
+        this.order.reset();
+        this.customer.reset();
+        this.payment.reset();
+        this.product.clearCache();
+    }
+}
+/**
+ * Factory function to create an ECSuite instance.
+ *
+ * @param config - Optional configuration for the suite
+ * @returns A new ECSuite instance
+ *
+ * @example
+ * ```typescript
+ * const suite = createECSuite({
+ *   context: { customerId: "user-123" },
+ *   adapters: {
+ *     cart: myCartAdapter,
+ *     wishlist: myWishlistAdapter,
+ *   },
+ *   storage: { type: "local" },
+ * });
+ * ```
+ */
+export function createECSuite(config) {
+    return new ECSuite(config);
+}

package/dist/types/adapter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @module types/adapter
+ *
+ * Adapter interface definitions for server communication.
+ * Implement these interfaces to connect ECSuite to your backend.
+ */
+import type { CartData, CartItem, CustomerData, OrderData, PaymentData, ProductData, UUID } from "@marianmeres/collection-types";
+import type { DomainContext, WishlistData } from "./state.js";
+/** Base adapter result */
+export interface AdapterResult<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** Cart adapter interface */
+export interface CartAdapter {
+    /** Fetch current cart from server */
+    fetch(ctx: DomainContext): Promise<AdapterResult<CartData>>;
+    /** Add item to cart */
+    addItem(item: CartItem, ctx: DomainContext): Promise<AdapterResult<CartData>>;
+    /** Update item quantity */
+    updateItem(productId: UUID, quantity: number, ctx: DomainContext): Promise<AdapterResult<CartData>>;
+    /** Remove item from cart */
+    removeItem(productId: UUID, ctx: DomainContext): Promise<AdapterResult<CartData>>;
+    /** Clear all items */
+    clear(ctx: DomainContext): Promise<AdapterResult<CartData>>;
+    /** Sync full cart state (for optimistic update reconciliation) */
+    sync(cart: CartData, ctx: DomainContext): Promise<AdapterResult<CartData>>;
+}
+/** Wishlist adapter interface */
+export interface WishlistAdapter {
+    /** Fetch current wishlist from server */
+    fetch(ctx: DomainContext): Promise<AdapterResult<WishlistData>>;
+    /** Add item to wishlist */
+    addItem(productId: UUID, ctx: DomainContext): Promise<AdapterResult<WishlistData>>;
+    /** Remove item from wishlist */
+    removeItem(productId: UUID, ctx: DomainContext): Promise<AdapterResult<WishlistData>>;
+    /** Clear all items */
+    clear(ctx: DomainContext): Promise<AdapterResult<WishlistData>>;
+    /** Sync full wishlist state */
+    sync(wishlist: WishlistData, ctx: DomainContext): Promise<AdapterResult<WishlistData>>;
+}
+/** Order create payload (status is set by server) */
+export type OrderCreatePayload = Omit<OrderData, "status">;
+/** Order adapter interface (read + create only) */
+export interface OrderAdapter {
+    /** Fetch all orders for customer */
+    fetchAll(ctx: DomainContext): Promise<AdapterResult<OrderData[]>>;
+    /** Fetch single order by ID */
+    fetchOne(orderId: UUID, ctx: DomainContext): Promise<AdapterResult<OrderData>>;
+    /** Create new order */
+    create(order: OrderCreatePayload, ctx: DomainContext): Promise<AdapterResult<OrderData>>;
+}
+/** Customer adapter interface (read + limited update) */
+export interface CustomerAdapter {
+    /** Fetch customer data */
+    fetch(ctx: DomainContext): Promise<AdapterResult<CustomerData>>;
+    /** Update customer data (partial) */
+    update(data: Partial<CustomerData>, ctx: DomainContext): Promise<AdapterResult<CustomerData>>;
+}
+/** Payment adapter interface (read-only) */
+export interface PaymentAdapter {
+    /** Fetch payments for an order */
+    fetchForOrder(orderId: UUID, ctx: DomainContext): Promise<AdapterResult<PaymentData[]>>;
+    /** Fetch single payment by ID */
+    fetchOne(paymentId: UUID, ctx: DomainContext): Promise<AdapterResult<PaymentData>>;
+}
+/** Product adapter interface (read-only with batch support) */
+export interface ProductAdapter {
+    /** Fetch single product by ID */
+    fetchOne(productId: UUID, ctx: DomainContext): Promise<AdapterResult<ProductData>>;
+    /** Fetch multiple products by IDs */
+    fetchMany(productIds: UUID[], ctx: DomainContext): Promise<AdapterResult<ProductData[]>>;
+}

package/dist/types/adapter.js

@@ -0,0 +1,7 @@
+/**
+ * @module types/adapter
+ *
+ * Adapter interface definitions for server communication.
+ * Implement these interfaces to connect ECSuite to your backend.
+ */
+export {};

package/dist/types/events.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @module types/events
+ *
+ * Event type definitions for the ECSuite event system.
+ * Subscribe to these events to react to domain state changes.
+ */
+import type { UUID } from "@marianmeres/collection-types";
+import type { DomainError, DomainState } from "./state.js";
+/** Domain identifiers */
+export type DomainName = "cart" | "wishlist" | "order" | "customer" | "payment" | "product";
+/** Event types emitted by the suite */
+export type ECSuiteEventType = "domain:state:changed" | "domain:error" | "domain:synced" | "cart:item:added" | "cart:item:updated" | "cart:item:removed" | "cart:cleared" | "wishlist:item:added" | "wishlist:item:removed" | "wishlist:cleared" | "order:created" | "order:fetched" | "customer:updated" | "customer:fetched" | "payment:fetched" | "product:fetched";
+/** Base event data */
+export interface ECSuiteEventBase {
+    /** Event timestamp */
+    timestamp: number;
+    /** Domain that emitted the event */
+    domain: DomainName;
+}
+/** State change event */
+export interface StateChangedEvent extends ECSuiteEventBase {
+    type: "domain:state:changed";
+    previousState: DomainState;
+    newState: DomainState;
+}
+/** Error event */
+export interface ErrorEvent extends ECSuiteEventBase {
+    type: "domain:error";
+    error: DomainError;
+}
+/** Sync completed event */
+export interface SyncedEvent extends ECSuiteEventBase {
+    type: "domain:synced";
+}
+/** Cart item added event */
+export interface CartItemAddedEvent extends ECSuiteEventBase {
+    type: "cart:item:added";
+    domain: "cart";
+    productId: UUID;
+    quantity: number;
+}
+/** Cart item updated event */
+export interface CartItemUpdatedEvent extends ECSuiteEventBase {
+    type: "cart:item:updated";
+    domain: "cart";
+    productId: UUID;
+    previousQuantity: number;
+    newQuantity: number;
+}
+/** Cart item removed event */
+export interface CartItemRemovedEvent extends ECSuiteEventBase {
+    type: "cart:item:removed";
+    domain: "cart";
+    productId: UUID;
+}
+/** Cart cleared event */
+export interface CartClearedEvent extends ECSuiteEventBase {
+    type: "cart:cleared";
+    domain: "cart";
+}
+/** Wishlist item added event */
+export interface WishlistItemAddedEvent extends ECSuiteEventBase {
+    type: "wishlist:item:added";
+    domain: "wishlist";
+    productId: UUID;
+}
+/** Wishlist item removed event */
+export interface WishlistItemRemovedEvent extends ECSuiteEventBase {
+    type: "wishlist:item:removed";
+    domain: "wishlist";
+    productId: UUID;
+}
+/** Wishlist cleared event */
+export interface WishlistClearedEvent extends ECSuiteEventBase {
+    type: "wishlist:cleared";
+    domain: "wishlist";
+}
+/** Order created event */
+export interface OrderCreatedEvent extends ECSuiteEventBase {
+    type: "order:created";
+    domain: "order";
+    orderId?: UUID;
+}
+/** Order fetched event */
+export interface OrderFetchedEvent extends ECSuiteEventBase {
+    type: "order:fetched";
+    domain: "order";
+}
+/** Customer updated event */
+export interface CustomerUpdatedEvent extends ECSuiteEventBase {
+    type: "customer:updated";
+    domain: "customer";
+}
+/** Customer fetched event */
+export interface CustomerFetchedEvent extends ECSuiteEventBase {
+    type: "customer:fetched";
+    domain: "customer";
+}
+/** Payment fetched event */
+export interface PaymentFetchedEvent extends ECSuiteEventBase {
+    type: "payment:fetched";
+    domain: "payment";
+}
+/** Product fetched event */
+export interface ProductFetchedEvent extends ECSuiteEventBase {
+    type: "product:fetched";
+    domain: "product";
+    productId: UUID;
+}
+/** All event types union */
+export type ECSuiteEvent = StateChangedEvent | ErrorEvent | SyncedEvent | CartItemAddedEvent | CartItemUpdatedEvent | CartItemRemovedEvent | CartClearedEvent | WishlistItemAddedEvent | WishlistItemRemovedEvent | WishlistClearedEvent | OrderCreatedEvent | OrderFetchedEvent | CustomerUpdatedEvent | CustomerFetchedEvent | PaymentFetchedEvent | ProductFetchedEvent;

package/dist/types/events.js

@@ -0,0 +1,7 @@
+/**
+ * @module types/events
+ *
+ * Event type definitions for the ECSuite event system.
+ * Subscribe to these events to react to domain state changes.
+ */
+export {};

package/dist/types/mod.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module types
+ *
+ * Type exports for @marianmeres/ecsuite.
+ * Re-exports all types from state, adapter, and events modules.
+ */
+export * from "./state.js";
+export * from "./adapter.js";
+export * from "./events.js";

package/dist/types/mod.js

@@ -0,0 +1,9 @@
+/**
+ * @module types
+ *
+ * Type exports for @marianmeres/ecsuite.
+ * Re-exports all types from state, adapter, and events modules.
+ */
+export * from "./state.js";
+export * from "./adapter.js";
+export * from "./events.js";

package/dist/types/state.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module types/state
+ *
+ * Domain state and context type definitions.
+ * Core types for domain state management and data structures.
+ */
+import type { CartItem, ProductData, UUID } from "@marianmeres/collection-types";
+/** Domain state progression */
+export type DomainState = "initializing" | "ready" | "syncing" | "error";
+/** Error information structure */
+export interface DomainError {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Operation that failed */
+    operation: string;
+    /** Original error for debugging */
+    originalError?: unknown;
+}
+/** Base state wrapper for all domains */
+export interface DomainStateWrapper<T> {
+    /** Current domain state */
+    state: DomainState;
+    /** Domain data (null during initialization or after critical error) */
+    data: T | null;
+    /** Error information when state is "error" */
+    error: DomainError | null;
+    /** Timestamp of last successful sync */
+    lastSyncedAt: number | null;
+}
+/** Context passed to adapters and events */
+export interface DomainContext {
+    /** Optional customer ID */
+    customerId?: UUID;
+    /** Optional session ID */
+    sessionId?: UUID;
+}
+/** Wishlist item structure (not yet in collection-types) */
+export interface WishlistItem {
+    /** Product model_id reference */
+    product_id: UUID;
+    /** Timestamp when item was added */
+    added_at?: number;
+}
+/** Wishlist data structure (not yet in collection-types) */
+export interface WishlistData {
+    items: WishlistItem[];
+}
+/** Cart item enriched with product data */
+export interface EnrichedCartItem extends CartItem {
+    /** Product data (null if not found) */
+    product: ProductData | null;
+    /** Line total: quantity * price (0 if no product or price) */
+    lineTotal: number;
+}
+/** Wishlist item enriched with product data */
+export interface EnrichedWishlistItem extends WishlistItem {
+    /** Product data (null if not found) */
+    product: ProductData | null;
+}

package/dist/types/state.js

@@ -0,0 +1,7 @@
+/**
+ * @module types/state
+ *
+ * Domain state and context type definitions.
+ * Core types for domain state management and data structures.
+ */
+export {};

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@marianmeres/ecsuite",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "dist/mod.js",
+	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
+	"author": "Marian Meres",
+	"license": "MIT",
+	"dependencies": {
+		"@marianmeres/clog": "^3.15.0",
+		"@marianmeres/collection-types": "^1.11.0",
+		"@marianmeres/pubsub": "^2.4.5",
+		"@marianmeres/store": "^2.4.2"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/marianmeres/ecsuite.git"
+	},
+	"bugs": {
+		"url": "https://github.com/marianmeres/ecsuite/issues"
+	}
+}