@revenexx/cover 0.1.0

package/app/interfaces/account/order-list.ts

@@ -0,0 +1,47 @@
+export type AccountOrderStatus =
+	| "processing"
+	| "approval-pending"
+	| "shipped"
+	| "delivered"
+	| "cancelled";
+
+export type AccountOrderPaymentStatus = "open" | "paid" | "refunded";
+
+export interface AccountOrderPosition {
+	readonly id: string;
+	readonly sku: string;
+	readonly name: string;
+	readonly image?: string;
+	readonly quantity: number;
+	readonly unitPrice: number;
+	readonly lineTotal: number;
+	readonly categorySlug?: string;
+	readonly subcategorySlug?: string;
+}
+
+export interface AccountOrder {
+	readonly id: string;
+	readonly date: string;
+	readonly status: AccountOrderStatus;
+	readonly paymentStatus: AccountOrderPaymentStatus;
+	/** Net order total. */
+	readonly total: number;
+	readonly currency: string;
+	/** Customer's own order/PO number from the checkout. */
+	readonly orderNumber?: string;
+	readonly positions: AccountOrderPosition[];
+	readonly deliveryAddress?: string;
+	readonly billingAddress?: string;
+	/** Payment method key (invoice, po_number, cost_center). */
+	readonly paymentMethod?: string;
+	/** Carrier tracking once the order shipped. */
+	readonly tracking?: { carrier: string; trackingNumber: string };
+	/** Fulfillment milestones for the order progress display. */
+	readonly progress?: { step: "ordered" | "processing" | "shipped" | "delivered"; date?: string }[];
+	/** Approvers when the order awaits approval. */
+	readonly approvers?: string[];
+}
+
+export interface AccountOrderListResponse {
+	readonly orders: AccountOrder[];
+}

package/app/interfaces/account/order-lists.ts

@@ -0,0 +1,35 @@
+/**
+ * Order lists (shopping lists / label lists): saved position collections
+ * that flow back into the cart. Whole positions are stored — article,
+ * quantity, position texts and cost center (BRW-derived, generic).
+ */
+
+export type OrderListKind = "shopping" | "label";
+
+export interface OrderListPosition {
+	id: string;
+	sku: string;
+	name: string;
+	image?: string;
+	quantity: number;
+	unit?: string;
+	price: number;
+	taxRate?: number;
+	costCenterId?: string;
+	positionTexts?: string[];
+	customSku?: string;
+	categorySlug?: string;
+	subcategorySlug?: string;
+}
+
+export interface OrderList {
+	id: string;
+	name: string;
+	kind: OrderListKind;
+	/** Shared with the whole organization (read access). */
+	public: boolean;
+	owner: { id: string; name: string };
+	positions: OrderListPosition[];
+	createdAt: string;
+	updatedAt: string;
+}

package/app/interfaces/account/profile.ts

@@ -0,0 +1,17 @@
+export interface AccountProfile {
+	readonly name: string;
+	readonly email: string;
+	readonly initials: string;
+	readonly phone: string;
+	readonly company: string;
+}
+
+export interface AccountProfileUpdateInput {
+	readonly phone: string;
+	readonly company: string;
+}
+
+export interface AccountProfileFormState {
+	phone: string;
+	company: string;
+}

package/app/interfaces/account.ts

@@ -0,0 +1,3 @@
+import type { AccountProfile } from "../interfaces/account/profile";
+
+export type User = AccountProfile;

package/app/interfaces/address.ts

@@ -0,0 +1,9 @@
+export interface Address {
+	id: string;
+	companyName: string;
+	contactName: string;
+	street: string;
+	city: string;
+	postalCode: string;
+	country: string;
+}

package/app/interfaces/auth.ts

@@ -0,0 +1,104 @@
+/**
+ * B2B roles a user can act in. Personas in the mock auth service cover one
+ * role each so flows can be simulated per role; the platform will provide
+ * real role claims later.
+ */
+export type AuthRole = "buyer" | "approver" | "admin" | "requester";
+
+export interface AuthUser {
+	$id: string;
+	name: string;
+	email: string;
+	role?: AuthRole;
+}
+
+/**
+ * B2B registration paths (IS8/BRW pattern): new customers register with
+ * full company + address data, existing customers link their account via
+ * customer number.
+ */
+export type RegistrationMode = "new" | "existing";
+
+/** Company profile collected at registration — stored as a registration request. */
+export interface RegistrationProfile {
+	mode: RegistrationMode;
+	company: string;
+	vatId?: string;
+	customerNumber?: string;
+	address?: {
+		street: string;
+		streetNumber: string;
+		zip: string;
+		city: string;
+		country: string;
+	};
+	salutation?: string;
+	jobTitle?: string;
+	phone?: string;
+}
+
+export interface RegisterInput {
+	email: string;
+	password: string;
+	name?: string;
+	profile?: RegistrationProfile;
+}
+
+export interface LoginInput {
+	email: string;
+	password: string;
+}
+
+export interface StoredSession {
+	id: string;
+	expire: string;
+	/** Set for SDK sessions — carries the platform session for server calls. */
+	fallbackCookie?: string;
+	/** Set for mock sessions — references the signed-in demo persona. */
+	personaId?: string;
+	/** Set for public-API sessions — the platform user behind the session. */
+	userId?: string;
+	/** Set for public-API sessions — the customers-app contact (cart owner). */
+	contactId?: string;
+	/** Set for public-API sessions — the contact's organization (price scope). */
+	organizationId?: string;
+}
+
+export interface LoginFormState {
+	email: string;
+	password: string;
+}
+
+export interface RegisterFormState {
+	mode: RegistrationMode;
+	/* company */
+	company: string;
+	vatId: string;
+	customerNumber: string;
+	/* billing address (new customers) */
+	street: string;
+	streetNumber: string;
+	zip: string;
+	city: string;
+	country: string;
+	/* contact */
+	salutation: string;
+	firstName: string;
+	lastName: string;
+	jobTitle: string;
+	phone: string;
+	email: string;
+	/* account */
+	password: string;
+	passwordConfirm: string;
+	acceptTerms: boolean;
+}
+
+export interface ForgotPasswordFormState {
+	email: string;
+}
+
+export interface ResetPasswordFormState {
+	password: string;
+	passwordConfirm: string;
+}

package/app/interfaces/b2b.ts

@@ -0,0 +1,234 @@
+/**
+ * Generic B2B commerce model — organization configuration, cost centers,
+ * approval limits and approval workflows.
+ *
+ * Derived from real-world B2B procurement requirements (BANF processes,
+ * approval rules, booking accounts) but deliberately project-neutral:
+ * ERP-specific fields are mapped into this contract by live service
+ * implementations, never exposed to the UI. Every feature is individually
+ * switchable per organization (see OrganizationSettings) to cover the full
+ * configuration range from a simple webshop to a fully governed
+ * procurement setup.
+ */
+
+/* ------------------------------------------------------------------ */
+/* Organization configuration                                          */
+/* ------------------------------------------------------------------ */
+
+export interface OrganizationSettings {
+	/** Cost center accounting on positions and order head. */
+	costCenters: {
+		enabled: boolean;
+		/** Every position must carry a cost center before ordering. */
+		required: boolean;
+	};
+	/** Approval limits / approval rules (see ApprovalLimit). */
+	approvals: { enabled: boolean };
+	/** Requisition workflows (see ApprovalWorkflow). */
+	workflows: { enabled: boolean };
+	cart: {
+		/** Cart export (CSV/XLSX) and print offered to users. */
+		exportEnabled: boolean;
+		/** Users may keep multiple named carts and switch between them. */
+		multipleCarts: boolean;
+		/** Net (B2B) or gross (B2C) price display. */
+		priceDisplay: "net" | "gross";
+		/** Minimum order value in shop currency; 0 disables the check. */
+		minOrderValue: number;
+	};
+	checkout: {
+		/** Guest ordering without an account, per customer type. */
+		guestOrdering: {
+			/** Business customers (company data required). */
+			b2b: boolean;
+			/** Private customers (no company data, gross prices). */
+			b2c: boolean;
+		};
+		/** The order/PO number is a mandatory field. */
+		orderNumberRequired: boolean;
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Cost centers                                                        */
+/* ------------------------------------------------------------------ */
+
+export interface CostCenter {
+	id: string;
+	code: string;
+	label: string;
+	/** Optional budget approval limit attached to this cost center. */
+	limit?: ApprovalLimit;
+}
+
+/* ------------------------------------------------------------------ */
+/* Approval limits & rules                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * What an approval limit measures:
+ * - `budget`       — accumulated spend against an available budget
+ * - `order-value`  — value of a single order/cart
+ * - `unit-price`   — highest unit price in the cart
+ * - `non-catalog`  — cart contains items outside the negotiated catalog
+ */
+export type ApprovalLimitType = "budget" | "order-value" | "unit-price" | "non-catalog";
+
+/** Whom the approval limit is attached to. */
+export type ApprovalLimitSubject =
+	| { type: "user"; userId: string }
+	| { type: "cost-center"; costCenterId: string };
+
+/**
+ * Who has to approve when the limit is exceeded, and within which time
+ * frame before the request escalates to the deputy.
+ */
+export interface ApprovalRule {
+	/** true → exceeding requires approval; false → informational only. */
+	required: boolean;
+	approverId?: string;
+	approverName?: string;
+	deputyId?: string;
+	deputyName?: string;
+	/** Hours the approver has before the request escalates to the deputy. */
+	timeLimitHours?: number;
+	deputyTimeLimitHours?: number;
+}
+
+export interface ApprovalLimit {
+	id: string;
+	type: ApprovalLimitType;
+	subject: ApprovalLimitSubject;
+	label: string;
+	/** Maximum amount the subject may spend independently; unused for `non-catalog`. */
+	maxAmount?: number;
+	/** Total budget; only for `budget` limits. */
+	totalBudget?: number;
+	/** Budget still available; only for `budget` limits. */
+	availableBudget?: number;
+	currency?: string;
+	/** Only `non-catalog` limits can be switched off; others are always on. */
+	active: boolean;
+	approval: ApprovalRule;
+}
+
+/**
+ * An approval limit evaluated against a concrete cart — returned by the
+ * cart calculation so the UI can render the approvals block above the CTA.
+ */
+export interface ApprovalLimitEvaluation {
+	limitId: string;
+	type: ApprovalLimitType;
+	label: string;
+	status: "within" | "exceeded";
+	/** Effective threshold (max amount or available budget). */
+	threshold?: number;
+	/** The cart value the limit was compared against. */
+	actual?: number;
+	exceededBy?: number;
+	approval: ApprovalRule;
+}
+
+/* ------------------------------------------------------------------ */
+/* Approval workflows & requisitions                                   */
+/* ------------------------------------------------------------------ */
+
+export type WorkflowStepType = "request" | "order";
+
+export interface ApprovalWorkflowStep {
+	type: WorkflowStepType;
+	/** Users allowed to act in this step. */
+	users: { id: string; name: string }[];
+}
+
+/**
+ * A requisition workflow: one or more `request` steps (requesters hand the
+ * requisition on) ending in an `order` step (orderers turn it into an
+ * actual order or reject it).
+ */
+export interface ApprovalWorkflow {
+	id: string;
+	name: string;
+	steps: ApprovalWorkflowStep[];
+}
+
+export type RequisitionStatus = "open" | "ordered" | "cancelled";
+
+export type WorkflowHistoryAction =
+	| "submitted"
+	| "forwarded"
+	| "approved"
+	| "escalated"
+	| "rejected"
+	| "ordered"
+	| "cancelled";
+
+/** One audit-trail entry of a requisition's workflow (compliance log). */
+export interface WorkflowHistoryEntry {
+	id: string;
+	stepSequence: number;
+	action: WorkflowHistoryAction;
+	actorName: string;
+	actionDate: string;
+	comment?: string;
+}
+
+export interface RequisitionItemSnapshot {
+	id: string;
+	sku: string;
+	name: string;
+	name2?: string;
+	image?: string;
+	quantity: number;
+	unit?: string;
+	price: number;
+	taxRate: number;
+	costCenterId?: string;
+	positionTexts?: string[];
+	customSku?: string;
+}
+
+/**
+ * A requisition (order request): a cart snapshot created by a requester,
+ * traveling through a workflow until an orderer places or rejects it.
+ */
+export interface Requisition {
+	id: string;
+	workflowId: string;
+	workflowName: string;
+	requestedBy: { id: string; name: string };
+	requestedAt: string;
+	status: RequisitionStatus;
+	totalValue: number;
+	items: RequisitionItemSnapshot[];
+	/** Workflow audit trail, newest entry last. */
+	history?: WorkflowHistoryEntry[];
+	/** Compared when merging requisitions into one cart. */
+	deliveryAddress?: {
+		company: string;
+		street: string;
+		postalCode: string;
+		city: string;
+		country: string;
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Per-user B2B context (BFF: /api/account/context)                    */
+/* ------------------------------------------------------------------ */
+
+export type B2BRole = "buyer" | "approver" | "admin" | "requester";
+
+/**
+ * Everything the storefront needs to know about the current user's B2B
+ * setup in one request: organization settings, assigned cost centers,
+ * applicable limits and workflow memberships.
+ */
+export interface B2BContext {
+	role: B2BRole | null;
+	settings: OrganizationSettings;
+	costCenters: CostCenter[];
+	defaultCostCenterId: string | null;
+	approvalLimits: ApprovalLimit[];
+	workflows: ApprovalWorkflow[];
+}

package/app/interfaces/cart-calculation.ts

@@ -0,0 +1,131 @@
+import type { ApprovalLimitEvaluation } from "./b2b";
+import type { CartItem } from "./cart-item";
+
+/**
+ * Cart calculation contract — the BFF computes everything the cart and the
+ * checkout summary display: per-line pricing, the ordered totals block,
+ * line hints, orderability and triggered spending limits.
+ *
+ * ERP-backed implementations map their document fields into this generic
+ * shape; the bundled mock implementation computes a sensible subset.
+ */
+
+/** Pricing override labels — when set, no prices are shown for the line. */
+export type PriceLabelCode = "free" | "on-request" | "by-result";
+
+export type CartLineHintType =
+	| "missing-cost-center"
+	| "quantity-adjusted"
+	| "replaced"
+	| "duplicate";
+
+export interface CartLineHint {
+	type: CartLineHintType;
+	/** i18n key into the cart namespace; params interpolated client-side. */
+	messageKey: string;
+	params?: Record<string, string | number>;
+}
+
+export interface CartLineSurcharge {
+	name: string;
+	/** Per-unit surcharge amount (net). */
+	amountPerUnit: number;
+}
+
+export type AvailabilityState = "in-stock" | "partial" | "out-of-stock";
+
+export interface CartLineAvailability {
+	state: AvailabilityState;
+	/** Exactly available quantity (spec: export shows the available part). */
+	availableQuantity: number;
+	deliveryDays?: number;
+}
+
+export interface CalculatedCartLine {
+	/** References CartItem.id. */
+	id: string;
+	quantity: number;
+	/** Quantity after server-side rules (min quantity / steps) applied. */
+	adjustedQuantity?: number;
+	unitPrice: number;
+	lineTotal: number;
+	priceLabel?: { code: PriceLabelCode; label: string };
+	surcharges: CartLineSurcharge[];
+	availability: CartLineAvailability;
+	hints: CartLineHint[];
+}
+
+/**
+ * One row of the summary block. Rows arrive pre-ordered; rows flagged
+ * `alwaysVisible` render even with amount 0 (spec: Warenwert, Versand,
+ * Total). `key` drives styling (e.g. total emphasis), `label` is
+ * display-ready (translated server-side or a dynamic ERP name).
+ */
+export interface CartTotalRow {
+	key:
+		| "subtotal"
+		| "surcharge"
+		| "min-order-value"
+		| "discount"
+		| "shipping"
+		| "tax"
+		| "rounding"
+		| "total";
+	label: string;
+	amount: number;
+	alwaysVisible?: boolean;
+	meta?: {
+		/** Tax rate for `tax` rows (e.g. 19). */
+		rate?: number;
+		/** Threshold for `min-order-value` rows. */
+		threshold?: number;
+		/** Amount missing to reach the minimum order value. */
+		missing?: number;
+	};
+}
+
+export type CartMessageSeverity = "error" | "warning" | "info";
+
+export interface CartMessage {
+	severity: CartMessageSeverity;
+	/**
+	 * Stable machine code, e.g. "no-shipping-method", "no-payment-method",
+	 * "cost-center-required", "cost-centers-unassigned".
+	 */
+	code: string;
+	/** i18n key into the cart namespace. */
+	messageKey: string;
+	params?: Record<string, string | number>;
+}
+
+export interface CartCalculationRequest {
+	items: CartItem[];
+	deliveryMethod?: string;
+}
+
+/**
+ * A spend incentive near its threshold (free shipping, volume discount) —
+ * rendered as a progress nudge in the cart summary.
+ */
+export interface CartIncentive {
+	key: "free-shipping" | "volume-discount";
+	label: string;
+	/** Threshold amount in shop currency. */
+	threshold: number;
+	/** Amount still missing; 0 when reached. */
+	missing: number;
+	reached: boolean;
+}
+
+export interface CartCalculation {
+	currency: string;
+	lines: CalculatedCartLine[];
+	totals: CartTotalRow[];
+	/** False disables the checkout CTA; `messages` carry the reasons. */
+	orderable: boolean;
+	messages: CartMessage[];
+	/** Approval limits evaluated against this cart (block above the CTA). */
+	approvalLimits: ApprovalLimitEvaluation[];
+	/** Spend incentives for the summary panel (revenue nudges). */
+	incentives?: CartIncentive[];
+}

package/app/interfaces/cart-item.ts

@@ -0,0 +1,45 @@
+export interface CartItemPriceTier {
+	minQuantity: number;
+	unitPrice: number;
+}
+
+/** Maximum quantity per position (spec: ERP accepts 6 digits). */
+export const CART_MAX_QUANTITY = 999999;
+
+/** Up to four free-text lines per position. */
+export const CART_POSITION_TEXT_COUNT = 4;
+
+export interface CartItem {
+	/** Product id (ProductList.id) — string, UUID in live mode. */
+	id: string;
+	/**
+	 * Unique line identity — the same article may appear on multiple
+	 * positions (e.g. loaded requisitions), so `id` alone is not a key.
+	 * Assigned by the cart store on insertion.
+	 */
+	lineKey?: string;
+	name: string;
+	/** Secondary name (type / dimension). */
+	name2?: string;
+	image: string;
+	sku: string;
+	/** Customer-own article number, editable on the position. */
+	customSku?: string;
+	price: number;
+	quantity: number;
+	/** Quantity unit (e.g. "Stück", "Pack"). */
+	unit?: string;
+	taxRate?: number;
+	priceTiers?: CartItemPriceTier[];
+	maxOrderQuantity?: number;
+	/** Cost center assigned to this position. */
+	costCenterId?: string;
+	/** Up to CART_POSITION_TEXT_COUNT free-text lines. */
+	positionTexts?: string[];
+	/** Item outside the negotiated catalog (non-catalog limits). */
+	nonCatalog?: boolean;
+	/** Set when the position belongs to a loaded requisition. */
+	requisitionId?: string;
+	categorySlug?: string;
+	subcategorySlug?: string;
+}

package/app/interfaces/checkout-draft.ts

@@ -0,0 +1,4 @@
+export interface CheckoutDraft {
+	formValues: Record<string, Record<string, unknown>>;
+	savedAt: string;
+}

package/app/interfaces/checkout.ts

@@ -0,0 +1,43 @@
+import type { Address } from "../interfaces/address";
+import type { DeliveryMethod, DeliveryOption } from "../interfaces/delivery";
+import type { PaymentMethod, PaymentOption } from "../interfaces/payment";
+
+export interface CostCenter {
+	id: string;
+	code: string;
+	label: string;
+}
+
+export interface CheckoutProfile {
+	addresses: Address[];
+	defaultShippingAddressId: string;
+	defaultBillingAddressId: string;
+	availablePaymentMethods: PaymentOption[];
+	defaultPaymentMethod: PaymentMethod;
+	costCenters: CostCenter[];
+	availableDeliveryMethods: DeliveryOption[];
+	defaultDeliveryMethod: DeliveryMethod;
+}
+
+export interface CheckoutOnePageForm {
+	shippingAddressId: string;
+	billingSameAsShipping: boolean;
+	billingAddressId: string;
+	deliveryMethod: DeliveryMethod;
+	requestedDate: string;
+	deliveryNote: string;
+	/** Ship available items immediately, the rest follows. */
+	partialDelivery: boolean;
+	paymentMethod: PaymentMethod;
+	poNumber: string;
+	costCenterId: string;
+	/** Customer order/PO number on the order head (mandatory per org flag). */
+	orderNumber: string;
+	/** Reference to a previously received quote. */
+	quoteNumber: string;
+	/** Skip the order confirmation e-mail for this order. */
+	noOrderConfirmation: boolean;
+	orderNote: string;
+	promoCode: string;
+	acceptedTerms: boolean;
+}

package/app/interfaces/delivery.ts

@@ -0,0 +1,13 @@
+/**
+ * Delivery method codes come from the shipping app (live) or the demo
+ * profile (mock) — generic strings, e.g. "standard", "express", "pickup".
+ */
+export type DeliveryMethod = string;
+
+export interface DeliveryOption {
+	method: DeliveryMethod;
+	label: string;
+	price: number;
+	/** Delivery estimate in business days, e.g. "1–2". */
+	eta: string;
+}