@openlup/core 0.21.0 → 0.22.0

package/src/fulfillment/normalizedFulfillmentFacts.ts

@@ -0,0 +1,52 @@
+import {
+  parseNormalizedFulfillmentFact,
+  parseTransitionConflict,
+  type CompatibleNormalizedFulfillmentFact as CoreCompatibleNormalizedFulfillmentFact,
+  type FulfillmentTransitionSnapshot as CoreFulfillmentTransitionSnapshot,
+  type NormalizedFulfillmentFact as CoreNormalizedFulfillmentFact,
+  type NormalizedFulfillmentFactV0 as CoreNormalizedFulfillmentFactV0,
+  type NormalizedFulfillmentFactV1 as CoreNormalizedFulfillmentFactV1,
+  type TransitionConflict as CoreTransitionConflict,
+} from "./facts.js";
+import {
+  CANONICAL_LOCAL_FULFILLMENT_STATUSES,
+} from "./statusMap.js";
+import type { CanonicalLocalFulfillmentStatus } from "./types.js";
+
+/** Application binding: core evidence narrowed to the single Layer B status canon. */
+export type CanonicalNormalizedFulfillmentFact =
+  CoreNormalizedFulfillmentFact<CanonicalLocalFulfillmentStatus>;
+export type CanonicalNormalizedFulfillmentFactV1 =
+  CoreNormalizedFulfillmentFactV1<CanonicalLocalFulfillmentStatus>;
+export type CanonicalNormalizedFulfillmentFactV0 =
+  CoreNormalizedFulfillmentFactV0<CanonicalLocalFulfillmentStatus>;
+export type CanonicalCompatibleNormalizedFulfillmentFact =
+  CoreCompatibleNormalizedFulfillmentFact<CanonicalLocalFulfillmentStatus>;
+export type CanonicalFulfillmentTransitionSnapshot =
+  CoreFulfillmentTransitionSnapshot<CanonicalLocalFulfillmentStatus>;
+export type CanonicalTransitionConflict =
+  CoreTransitionConflict<CanonicalLocalFulfillmentStatus>;
+
+const CANONICAL_STATUSES = new Set<string>(CANONICAL_LOCAL_FULFILLMENT_STATUSES);
+
+export function isCanonicalLocalFulfillmentStatus(
+  value: string,
+): value is CanonicalLocalFulfillmentStatus {
+  return CANONICAL_STATUSES.has(value);
+}
+
+/** Strict unknown-input parser bound to the existing status canon. */
+export function parseFulfillmentFact(
+  value: unknown,
+): CanonicalNormalizedFulfillmentFact {
+  return parseNormalizedFulfillmentFact(value, {
+    isCanonicalStatus: isCanonicalLocalFulfillmentStatus,
+  });
+}
+
+/** Strict conflict parser bound to the same status canon. */
+export function parseFulfillmentTransitionConflict(value: unknown): CanonicalTransitionConflict {
+  return parseTransitionConflict(value, {
+    isCanonicalStatus: isCanonicalLocalFulfillmentStatus,
+  });
+}

package/src/fulfillment/statusMap.ts

@@ -0,0 +1,253 @@
+import type { CustomerFulfillmentStep } from "./types.js";
+
+export interface FulfillmentStatusStage {
+  /** Layer C — the provider-neutral customer step. */
+  customerStep: CustomerFulfillmentStep;
+  /** Precedence when several signals disagree — highest rank wins. */
+  rank: number;
+  /** Linear 5-step bar position (paid0 → delivered4); off-track states pinned. */
+  phaseIndex: number;
+  /** Whether this step sits on the normal paid→delivered track. */
+  onTrack: boolean;
+  /** i18n key for the short label (progress bar + cards). */
+  stepLabelKey: string;
+  /** Polish milestone label emitted server-side into the order-detail timeline. */
+  timelineLabel: string;
+  /** Key under `account:dashboard.panels.orders.trackingPhase.*` (start tile). */
+  trackingPhaseKey: string;
+  /** Short display label contributed with the status map. */
+  label: { pl: string; en: string };
+  /** Layer B `local_status` / durable FSM / order-level statuses resolving here. */
+  localStatus: readonly string[];
+  omsFulfillmentStatus: string[];
+  orderStatus: string[];
+  /** Extra provider/synonym tokens that also resolve here (for token→step). */
+  aliasTokens: string[];
+  /** Contributed effect metadata, pinned by the package test's projection digest. */
+  effects: { stock: string; handover: boolean; customerEmail: string | false };
+}
+
+export interface FulfillmentStatusMap {
+  version: number; comment: string;
+  stages: readonly FulfillmentStatusStage[];
+}
+
+export const FULFILLMENT_STATUS_MAP = {
+  version: 1,
+  // Contributed metadata below is retained verbatim. The package-local test pins
+  // the projection digest, token round-trips and helpers; it does not check host
+  // provider dictionaries or i18n resources.
+  comment:
+    "SINGLE SOURCE OF TRUTH for fulfillment status across all layers. Layer C (customerStep) is the spine. Providers (Layer A) map ONLY to local_status (Layer B) in their own dictionary; the UI consumes only Layer C. statusMap.test.ts keeps every layer consistent.",
+  stages: [
+    {
+      customerStep: "paid",
+      rank: 1,
+      phaseIndex: 0,
+      onTrack: true,
+      stepLabelKey: "account:dashboard.ordersV2.steps.paid",
+      timelineLabel: "Oplacone",
+      trackingPhaseKey: "paid",
+      label: { pl: "Opłacone", en: "Paid" },
+      localStatus: [],
+      omsFulfillmentStatus: ["created"],
+      orderStatus: ["paid", "fulfillment_pending"],
+      aliasTokens: [],
+      effects: { stock: "reserved", handover: false, customerEmail: false },
+    },
+    {
+      customerStep: "accepted",
+      rank: 2,
+      phaseIndex: 1,
+      onTrack: true,
+      stepLabelKey: "account:dashboard.ordersV2.steps.accepted",
+      timelineLabel: "Przyjete do realizacji",
+      trackingPhaseKey: "accepted",
+      label: { pl: "Przyjęte", en: "Accepted" },
+      localStatus: ["provider_received"],
+      omsFulfillmentStatus: ["label_pending", "label_created"],
+      orderStatus: [],
+      aliasTokens: ["new", "accepted", "processing", "provider_attempt_recorded"],
+      effects: { stock: "reserved", handover: false, customerEmail: false },
+    },
+    {
+      customerStep: "packing",
+      rank: 3,
+      phaseIndex: 2,
+      onTrack: true,
+      stepLabelKey: "account:dashboard.ordersV2.steps.packing",
+      timelineLabel: "Przygotowane do wysylki",
+      trackingPhaseKey: "preparing",
+      label: { pl: "Przygotowanie", en: "Preparing" },
+      localStatus: ["picking", "packed"],
+      omsFulfillmentStatus: ["packed"],
+      orderStatus: [],
+      aliasTokens: ["picked", "in_fulfillment", "ready_for_packing", "awaiting_courier", "ready_for_pickup"],
+      effects: { stock: "consumed", handover: false, customerEmail: false },
+    },
+    {
+      customerStep: "transit",
+      rank: 4,
+      phaseIndex: 3,
+      onTrack: true,
+      stepLabelKey: "account:dashboard.ordersV2.steps.transit",
+      timelineLabel: "W drodze",
+      trackingPhaseKey: "in_transit",
+      label: { pl: "W drodze", en: "In transit" },
+      localStatus: ["in_transit"],
+      omsFulfillmentStatus: ["handed_over", "in_transit"],
+      orderStatus: [],
+      aliasTokens: ["shipped", "shipping", "out_for_delivery", "dispatched"],
+      effects: { stock: "consumed", handover: true, customerEmail: "shipment.dispatched" },
+    },
+    {
+      customerStep: "delivered",
+      rank: 7,
+      phaseIndex: 4,
+      onTrack: true,
+      stepLabelKey: "account:dashboard.ordersV2.steps.delivered",
+      timelineLabel: "Dostarczono",
+      trackingPhaseKey: "delivered",
+      label: { pl: "Dostarczone", en: "Delivered" },
+      localStatus: ["delivered"],
+      omsFulfillmentStatus: ["delivered"],
+      orderStatus: ["fulfilled"],
+      aliasTokens: ["delivery_delivered"],
+      effects: { stock: "consumed", handover: true, customerEmail: false },
+    },
+    {
+      customerStep: "exception",
+      rank: 5,
+      phaseIndex: 1,
+      onTrack: false,
+      stepLabelKey: "account:dashboard.ordersV2.status.exception",
+      timelineLabel: "Wymaga sprawdzenia",
+      trackingPhaseKey: "exception",
+      label: { pl: "Wymaga sprawdzenia", en: "Needs review" },
+      localStatus: ["exception"],
+      omsFulfillmentStatus: ["exception"],
+      orderStatus: [],
+      aliasTokens: ["shipping_failed", "failed", "suspended", "returned_to_sender"],
+      effects: { stock: "held", handover: false, customerEmail: "shipment.exception (provider exception before handoff)" },
+    },
+    {
+      customerStep: "cancelled",
+      rank: 6,
+      phaseIndex: 0,
+      onTrack: false,
+      stepLabelKey: "account:dashboard.ordersV2.status.cancelled",
+      timelineLabel: "Anulowano",
+      trackingPhaseKey: "cancelled",
+      label: { pl: "Anulowano", en: "Cancelled" },
+      localStatus: ["cancelled"],
+      omsFulfillmentStatus: ["cancelled"],
+      orderStatus: ["cancelled", "refunded"],
+      aliasTokens: ["canceled"],
+      effects: { stock: "released", handover: false, customerEmail: false },
+    },
+  ],
+} as const satisfies FulfillmentStatusMap;
+
+type CanonicalLocalFulfillmentStatus = import("./types.js").CanonicalLocalFulfillmentStatus;
+export const CANONICAL_LOCAL_FULFILLMENT_STATUSES: readonly CanonicalLocalFulfillmentStatus[] =
+  FULFILLMENT_STATUS_MAP.stages.flatMap((stage) => stage.localStatus);
+// Off-track steps render separately and are absent from the progress-bar spine.
+export const CUSTOMER_STEP_SEQUENCE: CustomerFulfillmentStep[] = ["paid", "accepted", "packing", "transit", "delivered"];
+
+// Provider strings arrive in varied spelling ("IN_FULFILLMENT", "in-fulfillment",
+// "Label Created") — compare on a canonical token so casing/separator drift never
+// silently changes the mapping.
+export function canonicalStatusToken(value: string | null | undefined): string | null {
+  const token = value?.trim().toLowerCase().replace(/[\s_-]+/g, "_");
+  return token || null;
+}
+
+const STAGE_BY_STEP: Record<CustomerFulfillmentStep, FulfillmentStatusStage> = Object.fromEntries(
+  FULFILLMENT_STATUS_MAP.stages.map((stage) => [stage.customerStep, stage]),
+) as unknown as Record<CustomerFulfillmentStep, FulfillmentStatusStage>;
+
+// token → customerStep, derived from the map (localStatus + FSM + orderStatus +
+// aliasTokens). The package-local fulfillment/statusMap.test.ts witness checks
+// that each contributed token round-trips to its declared customer step.
+const STEP_LOOKUP: Record<string, CustomerFulfillmentStep> = (() => {
+  const table: Record<string, CustomerFulfillmentStep> = {};
+  for (const stage of FULFILLMENT_STATUS_MAP.stages) {
+    for (const token of [
+      ...stage.localStatus,
+      ...stage.omsFulfillmentStatus,
+      ...stage.orderStatus,
+      ...stage.aliasTokens,
+    ]) {
+      const canon = canonicalStatusToken(token);
+      if (canon) table[canon] = stage.customerStep;
+    }
+  }
+  return table;
+})();
+
+/**
+ * Resolve a single raw token (a Layer B `local_status`, an FSM value, an order
+ * status, or a provider/synonym) to a customer step. Exact map lookup first, then
+ * a conservative substring fallback so an unknown FUTURE token never regresses to
+ * a misleading default — it returns null and the caller decides (generic label /
+ * "paid" floor). Never guesses a more-advanced state than the token implies.
+ */
+export function stepForToken(token: string | null | undefined): CustomerFulfillmentStep | null {
+  const canon = canonicalStatusToken(token);
+  if (!canon) return null;
+  const exact = STEP_LOOKUP[canon];
+  if (exact) return exact;
+  if (/deliver/.test(canon)) return "delivered";
+  if (/cancel/.test(canon)) return "cancelled";
+  if (/exception|fail/.test(canon)) return "exception";
+  if (/transit|dispatch|shipp|out_for/.test(canon)) return "transit";
+  if (/pack|pick|fulfil/.test(canon)) return "packing";
+  if (/label|accept|received|processing/.test(canon) || canon === "new") return "accepted";
+  if (/paid|created/.test(canon)) return "paid";
+  return null;
+}
+
+/**
+ * The single customer step for an order, from all its real signals (order status,
+ * durable fulfillment status, latest provider evidence). The most-advanced real
+ * signal wins by rank — so the internal `label_created` (set at OUR dispatch) can
+ * never overstate a box the provider has not started, and a real `picking`/
+ * `in_transit` is never held back by a stale internal state. Floors at "paid".
+ */
+export function customerStepFromSignals(tokens: Array<string | null | undefined>): CustomerFulfillmentStep {
+  let best: CustomerFulfillmentStep | null = null;
+  let bestRank = -1;
+  for (const token of tokens) {
+    const step = stepForToken(token);
+    if (!step) continue;
+    const rank = STAGE_BY_STEP[step].rank;
+    if (rank > bestRank) {
+      bestRank = rank;
+      best = step;
+    }
+  }
+  return best ?? "paid";
+}
+
+export function phaseIndexForStep(step: CustomerFulfillmentStep): number {
+  return STAGE_BY_STEP[step].phaseIndex;
+}
+
+/** i18n key for a step's short label (progress bar + cards). */
+export function stepLabelKey(step: CustomerFulfillmentStep): string {
+  return STAGE_BY_STEP[step].stepLabelKey;
+}
+
+/** Server-emitted Polish milestone label for the order-detail timeline. */
+export function timelineLabelForStep(step: CustomerFulfillmentStep): string {
+  return STAGE_BY_STEP[step].timelineLabel;
+}
+
+/** `panels.orders.trackingPhase.*` key for a step (start-page tile). */
+export function trackingPhaseKeyForStep(step: CustomerFulfillmentStep): string {
+  return STAGE_BY_STEP[step].trackingPhaseKey;
+}
+
+export function stepUsesTruckIcon(step: CustomerFulfillmentStep): boolean {
+  return step === "transit" || step === "delivered";
+}

package/src/fulfillment/trackingProgress.ts

@@ -0,0 +1,49 @@
+import type { FulfillmentProgressInput, FulfillmentProgressPresentation } from './types.js';
+import { CUSTOMER_STEP_SEQUENCE, phaseIndexForStep, stepForToken } from './statusMap.js';
+import type { CustomerFulfillmentStep } from './types.js';
+/** The host resolves its existing step; only actual recorded milestones complete. */
+export function fulfillmentProgressPresentation(order: FulfillmentProgressInput, step: CustomerFulfillmentStep): FulfillmentProgressPresentation | null {
+  const status = order.status.toLowerCase();
+  const rawPayment = order.paymentStatus?.toLowerCase() ?? "";
+  const payment = rawPayment === "paid" ? "succeeded" : rawPayment;
+  const paid = payment === "succeeded";
+  const terminal = status === "cancelled" || status === "refunded";
+  const orderMilestone = stepForToken(status);
+  const recordedOrderMilestone = orderMilestone !== null && orderMilestone !== "paid"
+    && CUSTOMER_STEP_SEQUENCE.includes(orderMilestone as typeof CUSTOMER_STEP_SEQUENCE[number]);
+  const parcelEvidence = recordedOrderMilestone || Boolean(order.fulfillmentStatus)
+    || Boolean(order.customerFulfillmentStep && step !== "paid" && !["draft", "failed", "expired"].includes(status))
+    || order.trackingTimeline.some((event) => {
+      const observed = stepForToken(event.eventType);
+      return observed !== null && observed !== "paid";
+    });
+  const advancedParcel = !terminal && parcelEvidence && step !== "paid";
+  return progressPresentation(order, step, paid, terminal, advancedParcel);
+}
+
+function progressPresentation(
+  order: FulfillmentProgressInput,
+  step: CustomerFulfillmentStep,
+  paid: boolean,
+  terminal: boolean,
+  advancedParcel: boolean,
+): FulfillmentProgressPresentation | null {
+  if (terminal || ["draft", "expired"].includes(order.status.toLowerCase())
+    || step === "exception" || step === "cancelled" || !paid && !advancedParcel) return null;
+  const completed = new Set<CustomerFulfillmentStep>(paid ? ["paid"] : []);
+  const record = (token: string | null | undefined) => {
+    const observed = stepForToken(token);
+    // No historical inference from an index, and no payment proof from parcel tokens.
+    if (observed && observed !== "paid" && CUSTOMER_STEP_SEQUENCE.includes(observed as typeof CUSTOMER_STEP_SEQUENCE[number])
+      && phaseIndexForStep(observed) <= phaseIndexForStep(step)) completed.add(observed);
+  };
+  if (advancedParcel) {
+    record(order.fulfillmentStatus);
+    record(step);
+    order.trackingTimeline.forEach((event) => record(event.eventType));
+  }
+  return {
+    completedSteps: [...completed],
+    currentStep: advancedParcel && step !== "delivered" ? step : null,
+  };
+}

package/src/fulfillment/types.ts

@@ -0,0 +1,12 @@
+export type CanonicalLocalFulfillmentStatus = "provider_received" | "picking" | "packed" | "in_transit" | "delivered" | "exception" | "cancelled";
+export type CustomerFulfillmentStep = "paid" | "accepted" | "packing" | "transit" | "delivered" | "exception" | "cancelled";
+
+export interface FulfillmentProgressInput {
+  status: string; paymentStatus?: string | null; fulfillmentStatus?: string | null;
+  customerFulfillmentStep?: CustomerFulfillmentStep | null;
+  trackingTimeline: { eventType: string }[];
+}
+export interface FulfillmentProgressPresentation {
+  completedSteps: CustomerFulfillmentStep[];
+  currentStep: CustomerFulfillmentStep | null;
+}