Merge pull request #69 from UrumiAI/feat/product-lifecycle-surfacing

[Domain] Product lifecycle surfacing

Author: vedanshujain

.changeset/product-lifecycle-surfacing.md

@@ -0,0 +1,65 @@
+---
+"@urumi/domain": minor
+"@urumi/store-postgres": minor
+"@urumi/service": minor
+"@urumi/plugin": minor
+---
+
+Product lifecycle surfacing (admin-UX Increment 2, slice 4): make a product's
+active/inactive/deleted state honest and browsable on the admin Products console,
+without adding a new mutating command.
+
+Ownership discovery (decisive for scope): activate/deactivate are ALREADY
+CMS-owned and already wired (`content:afterPublish`/`afterUnpublish` →
+`ProductCommerceStore.activate`/`deactivate`, landed alongside the sync hooks) and
+soft-delete is ALREADY CMS-owned and already wired (`content:afterDelete` →
+`softDeleteProductCommerce`, on both trash and permanent delete). There is no
+undiscovered domain-owned lifecycle command left to build — the gap was purely on
+the READ side, called out verbatim in the existing code: "there is no admin surface
+for browsing/restoring a soft-deleted product yet." This slice closes exactly that
+gap; it adds no new writer of `active`/`deletedAt`.
+
+- **Domain** — `ProductListFilter` gains `deleted?: boolean` (the tombstone axis,
+  a strict two-value equality filter mirroring `active`): omitted/`false` is the
+  ORIGINAL default (`deleted_at IS NULL`, unchanged for every existing caller);
+  `true` is the new archive view (`deleted_at IS NOT NULL`, mutually exclusive
+  with the live view — never both on one page). `ProductSummary` gains
+  `deletedAt: string | null`, present on every row (null on a live row, set only
+  in the archive view) so a consumer never has to guess whether the field exists.
+- **Adapters** — the fake and the Kysely store (sqlite + Postgres) flip the same
+  base `deleted_at` predicate the filter now parameterizes, contract-pinned
+  (`listProducts filter.deleted:true is the archive view`, `...composes with
+  active/productKind/search like every other axis`).
+- **Service** — `GET /admin/products?deleted=true` is the archive-view query
+  param; `GET /admin/products/:id` no longer collapses a soft-deleted row into
+  the SAME 404 an unknown id gets — it now returns 200 with `deletedAt` set (the
+  honest read-only tombstone), while the WRITE routes (`PATCH`, `restock`,
+  `remove-stock`) remain 404 for a deleted row via their own pre-existing
+  not_found guards — this is visibility only, never a path back to editability.
+- **Plugin** — the Products console's "Status" filter gets a 4th, mutually
+  exclusive option, "Archived (deleted)", so a merchant can never combine it with
+  Active/Inactive into a filter contradiction. A `deletedAt`-outranks-`active`
+  status label ("deleted" over "inactive") is shared by the list table, the "Open
+  product" picker, and the detail fields. Opening a soft-deleted product renders
+  a read-only tombstone banner (deletion timestamp + a note that existing orders
+  are unaffected, since an order snapshots price/title at purchase time) with NO
+  edit form and NO stock forms — editing or restocking a deleted product is
+  meaningless, and the write routes would 404 it anyway.
+
+Known, deliberately out-of-scope gap this slice surfaces but does not fix: restoring
+a CMS document from the trash does NOT undo a soft delete — `upsert` (the
+`content:afterSave` handler) never touches `deletedAt`/`active` by design, so a
+restored CMS document stays commerce-tombstoned with no self-heal. That is a new
+domain-owned RESTORE command, a separate, larger change (its own idempotency /
+ordering-watermark story), not a read-surfacing slice; flagged here for a follow-up
+decision, not built.
+
+Verification: the full `productCommerceStoreContract` (130 tests, sqlite + Postgres
+dialects), `admin-products-http.test.ts` against a live Postgres-backed server (incl.
+the new archive-filter and tombstone-detail cases, and the write-route
+still-blocked-for-deleted regression), and the plugin's workerd-on-Node sandbox
+(`products-page.sandbox.test.ts`, incl. the archived-filter query and the
+no-edit/no-stock-forms tombstone render) all pass. No new mutating command exists to
+race checkout, so no new Postgres concurrency test was needed; `listCommerceByIds`
+already omits soft-deleted rows (pre-existing, unchanged) so a deleted product was
+already unpurchasable before this change.

packages/domain/src/ports/product-commerce-store.ts

@@ -32,6 +32,23 @@ export interface ProductListFilter {
 	 *  `sku` (see the filter doc for why the two axes diverge). A row with a
 	 *  null `title`/`sku` simply cannot match that half — never a throw. */
 	search?: string;
+	/**
+	 * The tombstone axis (admin-UX Increment 2, "product lifecycle surfacing"
+	 * — the archive-view follow-up to the always-excludes-deleted default).
+	 * Deliberately NOT an OR-able array like `OrderListFilter.states`: a row is
+	 * either live or soft-deleted, a strict two-value axis, so a single
+	 * equality filter is the honest, minimal mirror of `active`.
+	 *  - omitted or `false` ⇒ the ORIGINAL default: only LIVE rows list
+	 *    (`deleted_at IS NULL`) — unchanged behavior, so every existing caller
+	 *    that never set this field keeps seeing exactly what it saw before.
+	 *  - `true` ⇒ the archive view: ONLY soft-deleted rows list
+	 *    (`deleted_at IS NOT NULL`). There is no "both" value — mixing live and
+	 *    tombstoned rows into one page would force every consumer to re-derive
+	 *    "is this archived" from `deletedAt` instead of the deliberate,
+	 *    filterable either/or a merchant actually wants (browse the catalog,
+	 *    or browse the archive — never both at once).
+	 */
+	deleted?: boolean;
 }
 
 /** A keyset cursor POSITION — the `(createdAt, productId)` of the last row of
@@ -68,6 +85,17 @@ export interface ProductSummary {
 	price: Money | null;
 	productKind: ProductKind;
 	active: boolean;
+	/**
+	 * The soft-delete tombstone timestamp (admin-UX Increment 2, "product
+	 * lifecycle surfacing"), ISO-8601 text like `createdAt` (never a `Date` —
+	 * this is a wire-adjacent projection, not the full `ProductCommerce` row).
+	 * Null for every LIVE row; non-null ONLY when `ProductListFilter.deleted:
+	 * true` requested the archive view (the default list never returns a
+	 * tombstoned row, so this field is null on every row of a default page —
+	 * present unconditionally, not "sometimes on the wire", so a consumer never
+	 * has to guess whether the field exists before reading it).
+	 */
+	deletedAt: string | null;
 	createdAt: string;
 }
 
@@ -432,10 +460,14 @@ export interface ProductCommerceStore {
 	 * `ProductSummary` PROJECTIONS (never the full `ProductCommerce`, and never
 	 * joined with `inventory` — the list must not N+1 into stock per row; a
 	 * per-row stock signal is deferred to the detail leaf's single-sku
-	 * `InventoryStore.getOnHand` read). Always excludes soft-deleted rows
-	 * (`deleted_at IS NULL`) — mirrors `listCommerceByIds`'s tombstone
-	 * discipline; there is no admin surface for browsing/restoring a
-	 * soft-deleted product yet.
+	 * `InventoryStore.getOnHand` read). Excludes soft-deleted rows
+	 * (`deleted_at IS NULL`) by DEFAULT — mirrors `listCommerceByIds`'s
+	 * tombstone discipline — UNLESS `filter.deleted: true` requests the archive
+	 * view (`deleted_at IS NOT NULL` instead), the "product lifecycle
+	 * surfacing" slice's one new axis: browse what was soft-deleted (there is
+	 * still no RESTORE — a soft delete's `active`/`deletedAt` are flipped only
+	 * by the CMS-sync/lifecycle paths, `softDelete`/`activate`/`deactivate`;
+	 * this list is read-only visibility, not a new mutation).
 	 *
 	 * Ordered `created_at DESC, product_id DESC` (newest-first, `product_id`
 	 * the stable tie-break — the primary key, exactly like `OrderSummary.id`).

packages/domain/src/testing/in-memory-product-commerce-store.ts

@@ -370,9 +370,11 @@ export class InMemoryProductCommerceStore implements ProductCommerceStore {
 
 	/** The ONE `ProductListFilter` predicate (mirrors `OrderStore`'s
 	 *  `#matchesFilter` / the Kysely adapter's shared predicate builder) —
-	 *  always excludes soft-deleted rows first. */
+	 *  excludes soft-deleted rows UNLESS `filter.deleted: true` requests the
+	 *  archive view (product lifecycle surfacing — see the port doc). */
 	#matchesFilter(row: ProductCommerce, filter: ProductListFilter): boolean {
-		if (row.deletedAt !== null) return false; // never list a tombstone.
+		const wantDeleted = filter.deleted === true;
+		if (wantDeleted !== (row.deletedAt !== null)) return false;
 		if (filter.active !== undefined && row.active !== filter.active) return false;
 		if (filter.productKind !== undefined && row.productKind !== filter.productKind) return false;
 		if (filter.search !== undefined) {
@@ -427,6 +429,7 @@ export class InMemoryProductCommerceStore implements ProductCommerceStore {
 			price: row.price,
 			productKind: row.productKind,
 			active: row.active,
+			deletedAt: row.deletedAt === null ? null : row.deletedAt.toISOString(),
 			createdAt: row.createdAt.toISOString(),
 		};
 	}

packages/domain/src/testing/product-commerce-store-contract.ts

@@ -1102,6 +1102,7 @@ export function productCommerceStoreContract(
 			expect(p.price).toEqual({ amount: 4200, currency: "EUR" });
 			expect(p.productKind).toBe("digital");
 			expect(p.active).toBe(true);
+			expect(p.deletedAt).toBeNull();
 			expect(p.createdAt).toBe("2026-07-10T01:00:00.000Z");
 		});
 
@@ -1119,7 +1120,7 @@ export function productCommerceStoreContract(
 			expect(products[0]).toMatchObject({ sku: null, title: null, price: null });
 		});
 
-		test("listProducts always excludes soft-deleted rows (no toggle exists yet)", async () => {
+		test("listProducts excludes soft-deleted rows by DEFAULT (filter.deleted omitted or false)", async () => {
 			const h = await makeStore();
 			await h.seedProduct(productRow({ id: "prod-live", createdAt: "2026-07-10T01:00:00.000Z" }));
 			await h.seedProduct(
@@ -1129,8 +1130,52 @@ export function productCommerceStoreContract(
 					deletedAt: "2026-07-10T03:00:00.000Z",
 				}),
 			);
-			const { products } = await h.store.listProducts({}, { limit: 25 });
-			expect(products.map((p) => p.productId)).toEqual(["prod-live"]);
+			const omitted = await h.store.listProducts({}, { limit: 25 });
+			expect(omitted.products.map((p) => p.productId)).toEqual(["prod-live"]);
+			const explicitFalse = await h.store.listProducts({ deleted: false }, { limit: 25 });
+			expect(explicitFalse.products.map((p) => p.productId)).toEqual(["prod-live"]);
+		});
+
+		test("listProducts filter.deleted:true is the archive view — ONLY soft-deleted rows list, projecting deletedAt", async () => {
+			const h = await makeStore();
+			await h.seedProduct(productRow({ id: "prod-live", createdAt: "2026-07-10T01:00:00.000Z" }));
+			await h.seedProduct(
+				productRow({
+					id: "prod-deleted",
+					createdAt: "2026-07-10T02:00:00.000Z",
+					deletedAt: "2026-07-10T03:00:00.000Z",
+				}),
+			);
+			const { products } = await h.store.listProducts({ deleted: true }, { limit: 25 });
+			expect(products.map((p) => p.productId)).toEqual(["prod-deleted"]);
+			expect(products[0]?.deletedAt).toBe("2026-07-10T03:00:00.000Z");
+		});
+
+		test("listProducts filter.deleted:true composes with active/productKind/search like every other axis", async () => {
+			const h = await makeStore();
+			await h.seedProduct(
+				productRow({
+					id: "deleted-digital",
+					productKind: "digital",
+					title: "Findable Deleted Ebook",
+					createdAt: "2026-07-10T01:00:00.000Z",
+					deletedAt: "2026-07-10T02:00:00.000Z",
+				}),
+			);
+			await h.seedProduct(
+				productRow({
+					id: "deleted-physical",
+					productKind: "physical",
+					title: "Findable Deleted Mug",
+					createdAt: "2026-07-10T01:30:00.000Z",
+					deletedAt: "2026-07-10T02:30:00.000Z",
+				}),
+			);
+			const { products } = await h.store.listProducts(
+				{ deleted: true, productKind: "digital", search: "findable" },
+				{ limit: 25 },
+			);
+			expect(products.map((p) => p.productId)).toEqual(["deleted-digital"]);
 		});
 
 		test("listProducts filters by active", async () => {

packages/plugin/src/admin/admin-products-client.ts

@@ -26,6 +26,10 @@ export interface ProductSummaryWire {
 	currency: string | null;
 	productKind: string;
 	active: boolean;
+	/** Soft-delete tombstone (product lifecycle surfacing). Null on every row
+	 *  of a default (live) page; non-null only in the archive view
+	 *  (`ProductsListFilter.deleted: true`). */
+	deletedAt: string | null;
 	createdAt: string;
 }
 
@@ -44,16 +48,25 @@ export interface ProductDetailWire {
 	heightMm: number | null;
 	productKind: string;
 	active: boolean;
+	/** Soft-delete tombstone (product lifecycle surfacing). Non-null ⇒ this IS
+	 *  the read-only archive view — the detail leaf renders it instead of the
+	 *  edit/stock forms (see `products-page.ts`'s `detailBlocks`). A 404 (never
+	 *  existed) is still `getProduct` returning `null`; a deleted row is a 200
+	 *  with this field set. */
+	deletedAt: string | null;
 	onHand: number;
 	createdAt: string;
 	updatedAt: string;
 }
 
 /** The list filter the console builds from its filter form. `active` is a
  *  tri-state string ("" ⇒ both) so the wire query mirrors the service's
- *  `active=true|false` param exactly. */
+ *  `active=true|false` param exactly. `deleted` is the archive-view toggle
+ *  (product lifecycle surfacing): omitted/false ⇒ the original default (live
+ *  rows only); true ⇒ ONLY soft-deleted rows. */
 export interface ProductsListFilter {
 	active?: boolean;
+	deleted?: boolean;
 	productKind?: string;
 	search?: string;
 }
@@ -275,6 +288,7 @@ export class AdminProductsClient {
 			q.set("cursor", opts.cursor);
 		} else {
 			if (filter.active !== undefined) q.set("active", filter.active ? "true" : "false");
+			if (filter.deleted !== undefined) q.set("deleted", filter.deleted ? "true" : "false");
 			if (filter.productKind !== undefined && filter.productKind.length > 0) {
 				q.set("productKind", filter.productKind);
 			}