@mohasinac/appkit 3.4.7 → 3.5.0

package/dist/features/shipments/components/AdminShipmentsView.js

@@ -0,0 +1,82 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { sieveFilter, SIEVE_OP } from "@mohasinac/appkit";
+import { sortBy } from "@mohasinac/appkit";
+import React from "react";
+import { FilterChipGroup, ListingLayout } from "../../../ui";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
+import { toRecordArray, toRelativeDate, toStringValue, } from "../../admin/hooks/useAdminListingData";
+import { DataListingView } from "../../admin/components/DataListingView";
+import { AdminShipmentEditorView } from "./AdminShipmentEditorView";
+import { ADMIN_BULK_ACTIONS, ROW_ACTION_META } from "../../products/constants/action-defs";
+import { formatPaise } from "../../../utils/number.formatter";
+const STATUS_OPTIONS = [
+    { id: "All", label: "All" },
+    { id: "planning", label: "Planning" },
+    { id: "ordered", label: "Ordered" },
+    { id: "in_transit", label: "In Transit" },
+    { id: "customs", label: "Customs" },
+    { id: "received", label: "Received" },
+    { id: "processing", label: "Processing" },
+    { id: "completed", label: "Completed" },
+    { id: "cancelled", label: "Cancelled" },
+];
+export function AdminShipmentsView({ children, ...props }) {
+    if (React.Children.count(children) > 0) {
+        return (_jsx(ListingLayout, { portal: "admin", ...props, children: children }));
+    }
+    const config = {
+        portal: "admin",
+        title: "Procurement Shipments",
+        searchPlaceholder: "Search by shipment number or supplier",
+        emptyLabel: "No shipments found",
+        filterKeys: ["status"],
+        defaultSort: sortBy("createdAt", "DESC"),
+        queryKey: ["admin", "shipments", "listing"],
+        endpoint: ADMIN_ENDPOINTS.SHIPMENTS,
+        sortOptions: [
+            { value: sortBy("createdAt", "DESC"), label: "Newest" },
+            { value: sortBy("etaDate", "ASC"), label: "ETA soonest" },
+            { value: sortBy("projectedProfitPaise", "DESC"), label: "Highest projected profit" },
+            { value: "shipmentNumber", label: "Shipment # A–Z" },
+        ],
+        mapRows: (response) => toRecordArray(response.shipments).map((item, index) => {
+            const totals = item.totals ?? {};
+            const totalsComputedAt = item.totalsComputedAt;
+            const updatedAt = item.updatedAt;
+            return {
+                id: toStringValue(item.id, `shipment-${index}`),
+                primary: toStringValue(item.shipmentNumber, "Untitled shipment"),
+                secondary: [toStringValue(item.supplierName, ""), toStringValue(item.status, "")]
+                    .filter(Boolean)
+                    .join(" · "),
+                status: toStringValue(item.status, "planning"),
+                updatedAt: toRelativeDate(updatedAt),
+                totalCost: formatPaise(Number(totals.totalShipmentCostPaise ?? 0)),
+                projectedProfit: formatPaise(Number(totals.projectedProfitPaise ?? 0)),
+                recalculating: !totalsComputedAt || (!!updatedAt && String(updatedAt) > String(totalsComputedAt)),
+            };
+        }),
+        getTotal: (response, mappedRows) => typeof response.meta?.total === "number" ? response.meta.total : mappedRows.length,
+        buildFilters: (state) => {
+            const parts = [];
+            if (state.status && state.status !== "All")
+                parts.push(sieveFilter("status", SIEVE_OP.EQ, state.status));
+            return parts.join(",") || undefined;
+        },
+        primaryAction: {
+            label: "New Shipment",
+            onClick: ({ openCreatePanel }) => openCreatePanel(),
+        },
+        buildBulkActions: (selection) => ADMIN_BULK_ACTIONS.shipments.map((id) => ({
+            id,
+            label: ROW_ACTION_META[id].label,
+            destructive: ROW_ACTION_META[id].destructive,
+            onClick: () => selection.clearSelection(),
+        })),
+        renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsx(FilterChipGroup, { label: "Status", tabs: STATUS_OPTIONS, value: pendingFilters.status ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, status: id })) })),
+        renderEditor: ({ editId, closePanel }) => (_jsx(AdminShipmentEditorView, { shipmentId: editId ?? undefined, onSaved: closePanel, embedded: true })),
+        resolveEditorTitle: ({ isCreate }) => (isCreate ? "New Shipment" : "Edit Shipment"),
+    };
+    return _jsx(DataListingView, { config: config });
+}

package/dist/features/shipments/components/ShipmentItemLinkModal.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+export interface ShipmentItemLinkModalProps {
+    shipmentId: string;
+    lotId: string;
+    itemId: string;
+    itemTitle: string;
+    isOpen: boolean;
+    onClose: () => void;
+    onLinked: () => void;
+}
+/**
+ * "Create pre-order link" (req #11) — manual, opt-in only, per main item.
+ * Shared between AdminShipmentLotItemsView and AdminShipmentProjectionsView.
+ */
+export declare function ShipmentItemLinkModal({ shipmentId, lotId, itemId, itemTitle, isOpen, onClose, onLinked, }: ShipmentItemLinkModalProps): React.JSX.Element;

package/dist/features/shipments/components/ShipmentItemLinkModal.js

@@ -0,0 +1,37 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+import { useApiMutation } from "@mohasinac/appkit/client";
+import { Button, FieldInput, Modal, Row, Stack, Text, Toggle } from "../../../ui";
+import { apiClient } from "../../../http";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
+import { ProductInlineSelect } from "../../seller/components/ProductInlineSelect";
+/**
+ * "Create pre-order link" (req #11) — manual, opt-in only, per main item.
+ * Shared between AdminShipmentLotItemsView and AdminShipmentProjectionsView.
+ */
+export function ShipmentItemLinkModal({ shipmentId, lotId, itemId, itemTitle, isOpen, onClose, onLinked, }) {
+    const [mode, setMode] = React.useState("create");
+    const [existingProductId, setExistingProductId] = React.useState(null);
+    const [categorySlugs, setCategorySlugs] = React.useState("");
+    const [brandSlug, setBrandSlug] = React.useState("");
+    const linkMutation = useApiMutation({
+        successMessage: "Item linked to product",
+        mutationFn: () => {
+            const body = mode === "link"
+                ? { mode: "link", productId: existingProductId }
+                : {
+                    mode: "create",
+                    categorySlugs: categorySlugs.split(",").map((s) => s.trim()).filter(Boolean),
+                    brandSlug: brandSlug.trim() || undefined,
+                };
+            return apiClient.post(ADMIN_ENDPOINTS.SHIPMENT_LOT_ITEM_LINK(shipmentId, lotId, itemId), body);
+        },
+        onSuccess: () => {
+            onLinked();
+            onClose();
+        },
+    });
+    const canSubmit = mode === "link" ? !!existingProductId : categorySlugs.trim().length > 0;
+    return (_jsx(Modal, { isOpen: isOpen, onClose: onClose, title: `Create pre-order link — ${itemTitle}`, size: "md", children: _jsxs(Stack, { gap: "md", children: [_jsx(Text, { variant: "secondary", children: "Links this item to a real product listing. This is a deliberate, one-time action \u2014 nothing links automatically." }), _jsxs(Row, { gap: "sm", align: "center", children: [_jsx(Toggle, { checked: mode === "create", onChange: (checked) => setMode(checked ? "create" : "link"), size: "sm" }), _jsx(Text, { children: mode === "create" ? "Create a new pre-order product" : "Link to an existing product" })] }), mode === "link" ? (_jsx(ProductInlineSelect, { scope: "admin", value: existingProductId, onChange: setExistingProductId, placeholder: "Search products\u2026" })) : (_jsxs(Stack, { gap: "sm", children: [_jsx(FieldInput, { name: "categorySlugs", label: "Category slugs (comma-separated)", required: true, value: categorySlugs, onChange: setCategorySlugs, placeholder: "category-action-figures" }), _jsx(FieldInput, { name: "brandSlug", label: "Brand slug (optional)", value: brandSlug, onChange: setBrandSlug })] })), _jsx(Button, { isLoading: linkMutation.isPending, disabled: !canSubmit, onClick: () => linkMutation.mutate(), children: mode === "create" ? "Create & Link" : "Link" })] }) }));
+}

package/dist/features/shipments/hooks/useShipments.d.ts

@@ -0,0 +1,69 @@
+import type { ShipmentDocument, ShipmentLot, ShipmentItem } from "../schemas/firestore";
+interface ListMeta {
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+interface ShipmentsListResponse {
+    shipments: ShipmentDocument[];
+    meta: ListMeta;
+}
+export interface UseShipmentsParams {
+    page?: number;
+    pageSize?: number;
+    sorts?: string;
+    filters?: string;
+}
+export declare function useShipments(params?: UseShipmentsParams): {
+    shipments: ShipmentDocument[];
+    meta: ListMeta | undefined;
+    isLoading: boolean;
+    error: string | null;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<NoInfer<ShipmentsListResponse>, Error>>;
+};
+export declare function useShipment(shipmentId?: string): {
+    shipment: NoInfer<ShipmentDocument> | undefined;
+    lots: ShipmentLot[];
+    isLoading: boolean;
+    error: string | null;
+    refetchShipment: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<NoInfer<ShipmentDocument>, Error>>;
+    refetchLots: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<NoInfer<{
+        lots: ShipmentLot[];
+    }>, Error>>;
+};
+interface ShipmentItemsListResponse {
+    items: ShipmentItem[];
+    meta: ListMeta;
+}
+export interface UseShipmentItemsParams {
+    page?: number;
+    pageSize?: number;
+    sorts?: string;
+}
+export declare function useShipmentItems(shipmentId?: string, lotId?: string, params?: UseShipmentItemsParams): {
+    items: ShipmentItem[];
+    meta: ListMeta | undefined;
+    isLoading: boolean;
+    error: string | null;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<NoInfer<ShipmentItemsListResponse>, Error>>;
+};
+interface ShipmentProjectionsResponse {
+    lots: ShipmentLot[];
+    meta: ListMeta;
+}
+export interface UseShipmentProjectionsParams {
+    page?: number;
+    pageSize?: number;
+    sorts?: string;
+    filters?: string;
+}
+export declare function useShipmentProjections(params?: UseShipmentProjectionsParams): {
+    lots: ShipmentLot[];
+    meta: ListMeta | undefined;
+    isLoading: boolean;
+    error: string | null;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<NoInfer<ShipmentProjectionsResponse>, Error>>;
+};
+export {};

package/dist/features/shipments/hooks/useShipments.js

@@ -0,0 +1,96 @@
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import { apiClient } from "../../../http";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
+export function useShipments(params = {}) {
+    const sp = new URLSearchParams();
+    if (params.page)
+        sp.set("page", String(params.page));
+    if (params.pageSize)
+        sp.set("pageSize", String(params.pageSize));
+    if (params.sorts)
+        sp.set("sorts", params.sorts);
+    if (params.filters)
+        sp.set("filters", params.filters);
+    const qs = sp.toString();
+    const { data, isLoading, error, refetch } = useQuery({
+        queryKey: ["admin", "shipments", qs],
+        queryFn: () => apiClient.get(`${ADMIN_ENDPOINTS.SHIPMENTS}${qs ? `?${qs}` : ""}`),
+    });
+    return {
+        shipments: data?.shipments ?? [],
+        meta: data?.meta,
+        isLoading,
+        error: error instanceof Error ? error.message : null,
+        refetch,
+    };
+}
+export function useShipment(shipmentId) {
+    const shipmentQuery = useQuery({
+        queryKey: ["admin", "shipment", shipmentId],
+        queryFn: () => apiClient.get(ADMIN_ENDPOINTS.SHIPMENT_BY_ID(shipmentId)),
+        enabled: !!shipmentId,
+    });
+    const lotsQuery = useQuery({
+        queryKey: ["admin", "shipment", shipmentId, "lots"],
+        queryFn: () => apiClient.get(ADMIN_ENDPOINTS.SHIPMENT_LOTS(shipmentId)),
+        enabled: !!shipmentId,
+    });
+    return {
+        shipment: shipmentQuery.data,
+        lots: lotsQuery.data?.lots ?? [],
+        isLoading: shipmentQuery.isLoading || lotsQuery.isLoading,
+        error: shipmentQuery.error instanceof Error
+            ? shipmentQuery.error.message
+            : lotsQuery.error instanceof Error
+                ? lotsQuery.error.message
+                : null,
+        refetchShipment: shipmentQuery.refetch,
+        refetchLots: lotsQuery.refetch,
+    };
+}
+export function useShipmentItems(shipmentId, lotId, params = {}) {
+    const sp = new URLSearchParams();
+    if (params.page)
+        sp.set("page", String(params.page));
+    if (params.pageSize)
+        sp.set("pageSize", String(params.pageSize));
+    if (params.sorts)
+        sp.set("sorts", params.sorts);
+    const qs = sp.toString();
+    const { data, isLoading, error, refetch } = useQuery({
+        queryKey: ["admin", "shipment", shipmentId, "lot", lotId, "items", qs],
+        queryFn: () => apiClient.get(`${ADMIN_ENDPOINTS.SHIPMENT_LOT_ITEMS(shipmentId, lotId)}${qs ? `?${qs}` : ""}`),
+        enabled: !!shipmentId && !!lotId,
+    });
+    return {
+        items: data?.items ?? [],
+        meta: data?.meta,
+        isLoading,
+        error: error instanceof Error ? error.message : null,
+        refetch,
+    };
+}
+export function useShipmentProjections(params = {}) {
+    const sp = new URLSearchParams();
+    if (params.page)
+        sp.set("page", String(params.page));
+    if (params.pageSize)
+        sp.set("pageSize", String(params.pageSize));
+    if (params.sorts)
+        sp.set("sorts", params.sorts);
+    if (params.filters)
+        sp.set("filters", params.filters);
+    const qs = sp.toString();
+    const { data, isLoading, error, refetch } = useQuery({
+        queryKey: ["admin", "shipments", "projections", qs],
+        queryFn: () => apiClient.get(`${ADMIN_ENDPOINTS.SHIPMENTS_PROJECTIONS}${qs ? `?${qs}` : ""}`),
+    });
+    return {
+        lots: data?.lots ?? [],
+        meta: data?.meta,
+        isLoading,
+        error: error instanceof Error ? error.message : null,
+        refetch,
+    };
+}

package/dist/features/shipments/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./schemas";
+export * from "./utils/cost-allocation";
+export * from "./hooks/useShipments";
+export { AdminShipmentsView } from "./components/AdminShipmentsView";
+export type { AdminShipmentsViewProps } from "./components/AdminShipmentsView";
+export { AdminShipmentEditorView } from "./components/AdminShipmentEditorView";
+export type { AdminShipmentEditorViewProps } from "./components/AdminShipmentEditorView";
+export { AdminShipmentLotItemsView } from "./components/AdminShipmentLotItemsView";
+export type { AdminShipmentLotItemsViewProps } from "./components/AdminShipmentLotItemsView";
+export { AdminShipmentProjectionsView } from "./components/AdminShipmentProjectionsView";

package/dist/features/shipments/index.js

@@ -0,0 +1,7 @@
+export * from "./schemas";
+export * from "./utils/cost-allocation";
+export * from "./hooks/useShipments";
+export { AdminShipmentsView } from "./components/AdminShipmentsView";
+export { AdminShipmentEditorView } from "./components/AdminShipmentEditorView";
+export { AdminShipmentLotItemsView } from "./components/AdminShipmentLotItemsView";
+export { AdminShipmentProjectionsView } from "./components/AdminShipmentProjectionsView";

package/dist/features/shipments/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureManifest } from "../../contracts";
+export declare const manifest: FeatureManifest;

package/dist/features/shipments/manifest.js

@@ -0,0 +1,26 @@
+export const manifest = {
+    name: "shipments",
+    i18nNamespace: "shipments",
+    envKeys: [],
+    routes: [
+        { segment: "[locale]/admin/shipments", exports: { default: "AdminShipmentsView" } },
+        { segment: "[locale]/admin/shipments/new", exports: { default: "AdminShipmentEditorView" } },
+        { segment: "[locale]/admin/shipments/[id]/edit", exports: { default: "AdminShipmentEditorView" } },
+        {
+            segment: "[locale]/admin/shipments/[id]/lots/[lotId]/items",
+            exports: { default: "AdminShipmentLotItemsView" },
+        },
+        { segment: "[locale]/admin/shipments/projections", exports: { default: "AdminShipmentProjectionsView" } },
+    ],
+    apiRoutes: [
+        { segment: "api/admin/shipments", methods: ["GET", "POST"] },
+        { segment: "api/admin/shipments/[id]", methods: ["GET", "PATCH", "DELETE"] },
+        { segment: "api/admin/shipments/[id]/lots", methods: ["GET", "POST"] },
+        { segment: "api/admin/shipments/[id]/lots/[lotId]", methods: ["GET", "PATCH", "DELETE"] },
+        { segment: "api/admin/shipments/[id]/lots/[lotId]/items", methods: ["GET", "POST"] },
+        { segment: "api/admin/shipments/[id]/lots/[lotId]/items/bulk", methods: ["POST"] },
+        { segment: "api/admin/shipments/[id]/lots/[lotId]/items/[itemId]", methods: ["PATCH", "DELETE"] },
+        { segment: "api/admin/shipments/[id]/lots/[lotId]/items/[itemId]/link", methods: ["POST"] },
+        { segment: "api/admin/shipments/projections", methods: ["GET"] },
+    ],
+};

package/dist/features/shipments/repository/shipment-items.repository.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shipment Items Repository — one doc per individually-tracked "main" item,
+ * FK'd to a lot + shipment. Capped at MAX_ITEMS_PER_LOT (500) per lot —
+ * exactly Firestore's native batched-write limit, so bulkCreate() writes an
+ * entire import in a single WriteBatch with no chunking logic.
+ */
+import { BaseRepository, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
+import { type ShipmentItem, type ShipmentItemCreateInput, type ShipmentItemUpdateInput } from "../schemas/firestore";
+export declare class ShipmentItemsRepository extends BaseRepository<ShipmentItem> {
+    constructor();
+    listByLot(lotId: string, model?: SieveModel): Promise<FirebaseSieveResult<ShipmentItem>>;
+    countByLot(lotId: string): Promise<number>;
+    /** Cheap bounded existence check — any item in this lot still linked to a product? */
+    hasLinkedItemsInLot(lotId: string): Promise<boolean>;
+    createItem(shipmentId: string, lotId: string, input: ShipmentItemCreateInput): Promise<ShipmentItem>;
+    /**
+     * Writes an entire bulk-paste import in a single Firestore WriteBatch
+     * (≤500 ops — Firestore's own batch cap, matching MAX_ITEMS_PER_LOT
+     * exactly, so no chunking is ever needed).
+     */
+    bulkCreate(shipmentId: string, lotId: string, rows: ShipmentItemCreateInput[]): Promise<number>;
+    updateItem(itemId: string, input: ShipmentItemUpdateInput): Promise<ShipmentItem>;
+    /** Clears a product link without touching the linked product itself. */
+    unlink(itemId: string): Promise<ShipmentItem>;
+    static readonly SIEVE_FIELDS: {
+        id: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        shipmentId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        lotId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        title: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        price: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        linkedProductId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        createdAt: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+    };
+}
+export declare const shipmentItemsRepository: ShipmentItemsRepository;

package/dist/features/shipments/repository/shipment-items.repository.js

@@ -0,0 +1,78 @@
+/**
+ * Shipment Items Repository — one doc per individually-tracked "main" item,
+ * FK'd to a lot + shipment. Capped at MAX_ITEMS_PER_LOT (500) per lot —
+ * exactly Firestore's native batched-write limit, so bulkCreate() writes an
+ * entire import in a single WriteBatch with no chunking logic.
+ */
+import { BaseRepository, } from "../../../providers/db-firebase";
+import { SHIPMENT_ITEM_COLLECTION, SHIPMENT_ITEM_FIELDS, MAX_ITEMS_PER_LOT, } from "../schemas/firestore";
+import { ValidationError } from "../../../errors";
+import { sieveAnd, sieveFilter, SIEVE_OP } from "../../../utils/sieve-builder";
+export class ShipmentItemsRepository extends BaseRepository {
+    constructor() {
+        super(SHIPMENT_ITEM_COLLECTION);
+    }
+    async listByLot(lotId, model) {
+        return this.sieveQuery({ ...(model ?? {}), filters: sieveAnd(sieveFilter("lotId", SIEVE_OP.EQ, lotId), model?.filters) }, ShipmentItemsRepository.SIEVE_FIELDS, { defaultPageSize: 50, maxPageSize: 100 });
+    }
+    async countByLot(lotId) {
+        const snap = await this.getCollection().where(SHIPMENT_ITEM_FIELDS.LOT_ID, "==", lotId).count().get();
+        return snap.data().count;
+    }
+    /** Cheap bounded existence check — any item in this lot still linked to a product? */
+    async hasLinkedItemsInLot(lotId) {
+        const snap = await this.getCollection()
+            .where(SHIPMENT_ITEM_FIELDS.LOT_ID, "==", lotId)
+            .where(SHIPMENT_ITEM_FIELDS.LINKED_PRODUCT_ID, "!=", null)
+            .limit(1)
+            .get();
+        return !snap.empty;
+    }
+    async createItem(shipmentId, lotId, input) {
+        const existing = await this.countByLot(lotId);
+        if (existing >= MAX_ITEMS_PER_LOT) {
+            throw new ValidationError(`Lot already has the maximum of ${MAX_ITEMS_PER_LOT} tracked items`);
+        }
+        return this.create({ ...input, shipmentId, lotId });
+    }
+    /**
+     * Writes an entire bulk-paste import in a single Firestore WriteBatch
+     * (≤500 ops — Firestore's own batch cap, matching MAX_ITEMS_PER_LOT
+     * exactly, so no chunking is ever needed).
+     */
+    async bulkCreate(shipmentId, lotId, rows) {
+        const existing = await this.countByLot(lotId);
+        if (existing + rows.length > MAX_ITEMS_PER_LOT) {
+            throw new ValidationError(`This import would exceed the ${MAX_ITEMS_PER_LOT}-item cap for this lot (${existing} already tracked, ${rows.length} in this import)`);
+        }
+        const batch = this.db.batch();
+        rows.forEach((row) => {
+            this.createInBatch(batch, { ...row, shipmentId, lotId });
+        });
+        await batch.commit();
+        return rows.length;
+    }
+    async updateItem(itemId, input) {
+        return this.update(itemId, input);
+    }
+    /** Clears a product link without touching the linked product itself. */
+    async unlink(itemId) {
+        // `null`, not `undefined` — prepareForFirestore() strips undefined
+        // values before every write, which would leave the fields untouched.
+        return this.update(itemId, {
+            linkedProductId: null,
+            linkedProductSlug: null,
+            linkedProductListingType: null,
+        });
+    }
+}
+ShipmentItemsRepository.SIEVE_FIELDS = {
+    id: { canFilter: true, canSort: false },
+    shipmentId: { canFilter: true, canSort: false },
+    lotId: { canFilter: true, canSort: false },
+    title: { canFilter: true, canSort: true },
+    price: { canFilter: true, canSort: true },
+    linkedProductId: { canFilter: true, canSort: false },
+    createdAt: { canFilter: true, canSort: true },
+};
+export const shipmentItemsRepository = new ShipmentItemsRepository();

package/dist/features/shipments/repository/shipment-lots.repository.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shipment Lots Repository — one doc per lot, FK'd to a shipment.
+ */
+import { BaseRepository, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
+import { type ShipmentLot, type ShipmentLotCreateInput, type ShipmentLotUpdateInput } from "../schemas/firestore";
+export declare class ShipmentLotsRepository extends BaseRepository<ShipmentLot> {
+    constructor();
+    listByShipment(shipmentId: string): Promise<ShipmentLot[]>;
+    createLot(shipmentId: string, shipmentStatus: ShipmentLot["shipmentStatus"], input: ShipmentLotCreateInput): Promise<ShipmentLot>;
+    updateLot(lotId: string, input: ShipmentLotUpdateInput): Promise<ShipmentLot>;
+    /**
+     * Real, paginated, persisted Projections list — one row per lot across
+     * every non-cancelled shipment, sorted by whichever computed field the
+     * admin picks. Reads the persisted rollup fields only; never recomputes.
+     */
+    listForProjections(model: SieveModel): Promise<FirebaseSieveResult<ShipmentLot>>;
+    static readonly SIEVE_FIELDS: {
+        id: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        shipmentId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        shipmentStatus: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        lotName: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        projectedProfitPaise: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        projectedRevenuePaise: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        createdAt: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+    };
+}
+export declare const shipmentLotsRepository: ShipmentLotsRepository;

package/dist/features/shipments/repository/shipment-lots.repository.js

@@ -0,0 +1,55 @@
+/**
+ * Shipment Lots Repository — one doc per lot, FK'd to a shipment.
+ */
+import { BaseRepository, } from "../../../providers/db-firebase";
+import { SHIPMENT_LOT_COLLECTION, SHIPMENT_LOT_FIELDS, } from "../schemas/firestore";
+export class ShipmentLotsRepository extends BaseRepository {
+    constructor() {
+        super(SHIPMENT_LOT_COLLECTION);
+    }
+    async listByShipment(shipmentId) {
+        const snapshot = await this.getCollection()
+            .where(SHIPMENT_LOT_FIELDS.SHIPMENT_ID, "==", shipmentId)
+            .orderBy(SHIPMENT_LOT_FIELDS.CREATED_AT, "asc")
+            .get();
+        return snapshot.docs.map((doc) => this.mapDoc(doc));
+    }
+    async createLot(shipmentId, shipmentStatus, input) {
+        return this.create({
+            ...input,
+            shipmentId,
+            shipmentStatus,
+            itemCount: 0,
+            mainItemsProjectedRevenuePaise: 0,
+            customsAllocatedPaise: 0,
+            shippingAllocatedPaise: 0,
+            totalLandedCostPaise: input.purchaseCostPaise,
+            projectedRevenuePaise: input.remainderEstimatedValuePaise ?? 0,
+            projectedProfitPaise: (input.remainderEstimatedValuePaise ?? 0) - input.purchaseCostPaise,
+        });
+    }
+    async updateLot(lotId, input) {
+        return this.update(lotId, input);
+    }
+    /**
+     * Real, paginated, persisted Projections list — one row per lot across
+     * every non-cancelled shipment, sorted by whichever computed field the
+     * admin picks. Reads the persisted rollup fields only; never recomputes.
+     */
+    async listForProjections(model) {
+        return this.sieveQuery(model, ShipmentLotsRepository.SIEVE_FIELDS, {
+            defaultPageSize: 25,
+            maxPageSize: 100,
+        });
+    }
+}
+ShipmentLotsRepository.SIEVE_FIELDS = {
+    id: { canFilter: true, canSort: false },
+    shipmentId: { canFilter: true, canSort: false },
+    shipmentStatus: { canFilter: true, canSort: false },
+    lotName: { canFilter: true, canSort: true },
+    projectedProfitPaise: { canFilter: true, canSort: true },
+    projectedRevenuePaise: { canFilter: true, canSort: true },
+    createdAt: { canFilter: true, canSort: true },
+};
+export const shipmentLotsRepository = new ShipmentLotsRepository();

package/dist/features/shipments/repository/shipments.repository.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Procurement Shipments Repository — header document only.
+ * Lots/items live in ShipmentLotsRepository / ShipmentItemsRepository.
+ */
+import { BaseRepository, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
+import { type ShipmentDocument, type ShipmentCreateInput, type ShipmentUpdateInput } from "../schemas/firestore";
+export declare class ShipmentsRepository extends BaseRepository<ShipmentDocument> {
+    constructor();
+    findByShipmentNumber(shipmentNumber: string): Promise<ShipmentDocument | null>;
+    private assertShipmentNumberAvailable;
+    create(input: ShipmentCreateInput): Promise<ShipmentDocument>;
+    update(shipmentId: string, input: ShipmentUpdateInput): Promise<ShipmentDocument>;
+    /** Cheap bounded existence check — any item under this shipment still linked to a product? */
+    private hasLinkedItems;
+    /**
+     * Blocks deletion if any item is still linked to a product — unlink first.
+     * Cascade-deleting the shipment's lots/items themselves is handled by the
+     * onShipmentDeleted Firestore trigger (Function #3), not here — this keeps
+     * the route fast regardless of how many items the shipment had.
+     */
+    delete(shipmentId: string): Promise<void>;
+    static readonly SIEVE_FIELDS: {
+        id: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        shipmentNumber: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        supplierName: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        status: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        etaDate: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        createdAt: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+    };
+    list(model: SieveModel): Promise<FirebaseSieveResult<ShipmentDocument>>;
+}
+export declare const shipmentsRepository: ShipmentsRepository;