@wocart/storefront 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 1.21.0 — 2026-10-24
+
+### Added
+
+- **A shopper's track-order page, with no script.** `lookupOrder(input,
+  request, client)` and `orderLookupInput` in `@wocart/storefront/astro`, for
+  an Astro Action a plain form posts: it answers `found` (the order),
+  `invalid-number` (not an order number — the server is not asked),
+  `invalid-phone`, `not-found` (a wrong number or phone, never saying which),
+  `rate-limited` (with the wait) or `failed`, and forwards the shopper's
+  address so the server's limit counts per shopper. The `orderStatus` route
+  takes the same input.
+- **The track-order page is a platform page.** `STOREFRONT_PAGE_PATHS.trackOrder`
+  is `/track-order` — `?order=<number>` fills its number in — so the platform
+  can link a shopper to it like the thank-you page, and every theme renders it
+  at the same place. `showsWidgetOn` treats it as a store page.
+- `SHOPPER_ORDER_JOURNEY`: the stages from `placed` to `delivered`, in order,
+  for a tracking page's progress; `returned` and `cancelled` end an order off
+  it.
+
+### Fixed
+
+- `notFound(Astro)` type-checks against Astro's own global and endpoint
+  context: `NotFoundContext.response.status` is optional, as Astro's
+  `ResponseInit` declares it. Nothing changes at runtime.
+
 ## 1.20.0 — 2026-10-24
 
 What every theme used to write itself is now the package's: the order form's

package/USAGE.md

@@ -111,6 +111,7 @@ break those links.
 | `landing` | `/lp/:slug` | a landing page | required when the store runs landing pages |
 | `checkout` | `/checkout` | the cart's checkout | required when the store turns the cart on |
 | `thankYou` | `/thank-you` | the order confirmation | required |
+| `trackOrder` | `/track-order` | where a shopper follows an order by its number and phone; `?order=<number>` fills the number in | required |
 
 How a theme implements them, in Astro's own terms:
 
@@ -1410,7 +1411,9 @@ number and the phone it was placed with prove it is theirs, as for a review.
 const found = await store.orders.status({ orderNumber, phone }, forwardedHeaders);
 if (found.success) {
   // found.data.stage: placed, confirmed, preparing, shipped, out_for_delivery,
-  //   delivered, returned (refused at the door) or cancelled — SHOPPER_ORDER_STAGES
+  //   delivered, returned (refused at the door) or cancelled — SHOPPER_ORDER_STAGES;
+  //   a progress bar shows SHOPPER_ORDER_JOURNEY, placed to delivered, which
+  //   returned and cancelled leave
   // found.data.lines, found.data.total, found.data.placedAt
   // found.data.tracking: { number, carrier } once the carrier has the parcel
 }
@@ -1419,6 +1422,34 @@ if (found.success) {
 ~~~
 
 It never answers the address, the notes or the merchant's own statuses.
+
+A theme's track-order page needs no script: an Astro Action posted by a plain
+form, with the outcome already worded in the few cases a page shows.
+
+~~~ts
+// src/actions/index.ts
+import { defineAction } from "astro:actions";
+import { lookupOrder, orderLookupInput } from "@wocart/storefront/astro";
+
+export const server = {
+  orderStatus: defineAction({
+    accept: "form",
+    input: orderLookupInput,
+    handler: (input, context) => lookupOrder(input, context.request, context.locals.store.client),
+  }),
+};
+~~~
+
+~~~astro
+---
+// src/pages/track.astro — the page renders from the same POST
+const lookup = Astro.getActionResult(actions.orderStatus)?.data;
+// lookup?.status: "found" (lookup.order), "invalid-number" (the server is not
+// asked), "invalid-phone", "not-found", "rate-limited" (retryAfterSeconds) or "failed"
+---
+<form method="POST" action={actions.orderStatus}>…</form>
+~~~
+
 From the browser, use the storefront routes' `orderStatus`.
 
 ### Meta browser primitives

package/dist/astro.d.ts

@@ -6,5 +6,7 @@ export { placeOrderInput, executePlaceOrder, collectForwardedHeaders, } from "./
 export type { PlaceOrderInput, PlaceOrderResult } from "./actions.js";
 export { runFormAction, resolveActionRedirectDecision } from "./middleware.js";
 export type { PrgDecision, ActionMiddlewareDeps, ActionDescriptor } from "./middleware.js";
+export { lookupOrder, orderLookupInput } from "./order-lookup.js";
+export type { OrderLookup, OrderLookupInput } from "./order-lookup.js";
 export { notFound, resolvePreviewStore, resolveStoreRequest } from "./store-request.js";
 export type { NotFoundContext, ResolvedStore, StoreRequestOptions, StoreRequestResolution } from "./store-request.js";

package/dist/astro.js

@@ -2,4 +2,5 @@ export { createProxyEndpoint } from "./endpoints/proxy.js";
 export { createStorefrontRoutes, REVIEWS_PAGE_DEFAULT, REVIEWS_PAGE_MAX, } from "./endpoints/storefront-routes.js";
 export { placeOrderInput, executePlaceOrder, collectForwardedHeaders, } from "./actions.js";
 export { runFormAction, resolveActionRedirectDecision } from "./middleware.js";
+export { lookupOrder, orderLookupInput } from "./order-lookup.js";
 export { notFound, resolvePreviewStore, resolveStoreRequest } from "./store-request.js";

package/dist/catalog.d.ts

@@ -10,6 +10,12 @@ export declare const PRODUCT_SORTS: readonly ["newest", "price-ascending", "pric
  * words.
  */
 export declare const SHOPPER_ORDER_STAGES: readonly ["placed", "confirmed", "preparing", "shipped", "out_for_delivery", "delivered", "returned", "cancelled"];
+/**
+ * The steps an order passes on its way to the shopper, in order — what a
+ * tracking page's progress shows. `returned` and `cancelled` end an order off
+ * this path, and a stage a newer server adds is on none of it.
+ */
+export declare const SHOPPER_ORDER_JOURNEY: readonly ["placed", "confirmed", "preparing", "shipped", "out_for_delivery", "delivered"];
 /**
  * The collections every store starts with, the likeliest to hold products
  * first: what to show when a page needs a collection and none was named (an

package/dist/catalog.js

@@ -19,6 +19,12 @@ export const SHOPPER_ORDER_STAGES = [
     "returned",
     "cancelled",
 ];
+/**
+ * The steps an order passes on its way to the shopper, in order — what a
+ * tracking page's progress shows. `returned` and `cancelled` end an order off
+ * this path, and a stage a newer server adds is on none of it.
+ */
+export const SHOPPER_ORDER_JOURNEY = ["placed", "confirmed", "preparing", "shipped", "out_for_delivery", "delivered"];
 /**
  * The collections every store starts with, the likeliest to hold products
  * first: what to show when a page needs a collection and none was named (an

package/dist/endpoints/storefront-routes.js

@@ -24,6 +24,7 @@
 import { z } from "zod";
 import { AbandonedCheckoutInputSchema, BasketLineInputSchema, DeliveryDestinationSchema, ProductQuoteInputSchema, WilayaIdSchema, } from "../domain.js";
 import { MAX_BASKET_LINES } from "../basket-line.js";
+import { orderLookupInput } from "../order-lookup.js";
 import { createProxyEndpoint, } from "./proxy.js";
 export const REVIEWS_PAGE_DEFAULT = 20;
 export const REVIEWS_PAGE_MAX = 50;
@@ -82,10 +83,6 @@ const reviewSubmitInput = z.object({
     grant: z.string().min(1).max(2048).optional(),
     uploads: z.array(z.string().min(1).max(64)).max(8).optional(),
 });
-const orderStatusInput = z.object({
-    orderNumber: z.string().min(1).max(64),
-    phone: z.string().min(1).max(32),
-});
 const reviewEligibilityInput = z.object({
     orderNumber: z.string().min(1).max(64),
     phone: z.string().min(1).max(32),
@@ -197,7 +194,7 @@ export function createStorefrontRoutes(options) {
         }),
         orderStatus: route({
             method: "POST",
-            inputSchema: orderStatusInput,
+            inputSchema: orderLookupInput,
             forwardAttribution: true,
             call: (client, proof, headers) => client.orders.status(proof, headers),
         }),

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { readCartQuote, readCouponOutcome, readShippingRates } from "./answer-re
 export { createQuoter } from "./quote.js";
 export type { Quoter, QuoterOptions, QuoteResult } from "./quote.js";
 export { isOrderNumber, ORDER_NUMBER_PATTERN } from "./order-number.js";
-export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_STAGES } from "./catalog.js";
+export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_JOURNEY, SHOPPER_ORDER_STAGES } from "./catalog.js";
 export { SEO_TEXT_LIMITS, jsonLd, productMeta, productStructuredData } from "./seo.js";
 export type { PageMeta, ProductStructuredDataOptions } from "./seo.js";
 export { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS } from "./reviews.js";

package/dist/index.js

@@ -25,7 +25,7 @@ export { isWilayaId } from "./wilaya-id.js";
 export { readCartQuote, readCouponOutcome, readShippingRates } from "./answer-readers.js";
 export { createQuoter } from "./quote.js";
 export { isOrderNumber, ORDER_NUMBER_PATTERN } from "./order-number.js";
-export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_STAGES } from "./catalog.js";
+export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_JOURNEY, SHOPPER_ORDER_STAGES } from "./catalog.js";
 export { SEO_TEXT_LIMITS, jsonLd, productMeta, productStructuredData } from "./seo.js";
 export { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS } from "./reviews.js";
 export { normalizeAlgerianPhone, toLocalAlgerianMobile } from "./phone.js";

package/dist/order-lookup.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A shopper following their order from a theme's own page: the form's input,
+ * and what the lookup comes to — in the few outcomes a page words, never a
+ * server code to interpret.
+ *
+ * ```ts
+ * // src/actions/index.ts
+ * orderStatus: defineAction({
+ *   accept: "form",
+ *   input: orderLookupInput,
+ *   handler: (input, context) => lookupOrder(input, context.request, context.locals.store.client),
+ * }),
+ * ```
+ */
+import { z } from "zod";
+import type { StoreClient } from "./client/index.js";
+import type { ShopperOrderStatus } from "./types.js";
+/** The order number and the phone it was placed with, as a form posts them. */
+export declare const orderLookupInput: z.ZodObject<{
+    orderNumber: z.ZodString;
+    phone: z.ZodString;
+}, z.core.$strip>;
+export type OrderLookupInput = z.infer<typeof orderLookupInput>;
+/**
+ * - `found` — the order, as a shopper may see it.
+ * - `invalid-number` — what was typed is not an order number; the server is not asked.
+ * - `invalid-phone` — the server cannot read the phone as a phone number.
+ * - `not-found` — no order has that number and phone; which of the two is wrong is never said.
+ * - `rate-limited` — too many tries from this shopper or for this order; try again after the wait.
+ * - `failed` — nothing the shopper can fix: try again later.
+ */
+export type OrderLookup = {
+    status: "found";
+    order: ShopperOrderStatus;
+} | {
+    status: "invalid-number";
+} | {
+    status: "invalid-phone";
+} | {
+    status: "not-found";
+} | {
+    status: "rate-limited";
+    retryAfterSeconds: number | null;
+} | {
+    status: "failed";
+};
+/**
+ * Look an order up for its shopper, forwarding their address so the server's
+ * limit counts per shopper rather than per theme server.
+ */
+export declare function lookupOrder(input: OrderLookupInput, request: Request, client: StoreClient): Promise<OrderLookup>;

package/dist/order-lookup.js

@@ -0,0 +1,44 @@
+/**
+ * A shopper following their order from a theme's own page: the form's input,
+ * and what the lookup comes to — in the few outcomes a page words, never a
+ * server code to interpret.
+ *
+ * ```ts
+ * // src/actions/index.ts
+ * orderStatus: defineAction({
+ *   accept: "form",
+ *   input: orderLookupInput,
+ *   handler: (input, context) => lookupOrder(input, context.request, context.locals.store.client),
+ * }),
+ * ```
+ */
+import { z } from "zod";
+import { collectForwardedHeaders } from "./actions.js";
+import { isOrderNumber } from "./order-number.js";
+/** The order number and the phone it was placed with, as a form posts them. */
+export const orderLookupInput = z.object({
+    orderNumber: z.string().trim().min(1).max(64),
+    phone: z.string().trim().min(1).max(32),
+});
+/**
+ * Look an order up for its shopper, forwarding their address so the server's
+ * limit counts per shopper rather than per theme server.
+ */
+export async function lookupOrder(input, request, client) {
+    if (!isOrderNumber(input.orderNumber))
+        return { status: "invalid-number" };
+    const result = await client.orders.status({ orderNumber: input.orderNumber.trim(), phone: input.phone.trim() }, collectForwardedHeaders(request));
+    if (result.success)
+        return { status: "found", order: result.data };
+    switch (result.domainError.code) {
+        case "ORDER_NOT_FOUND":
+            return { status: "not-found" };
+        case "VALIDATION_FAILED":
+            // The number was checked against the server's own pattern: what it refuses now is the phone.
+            return { status: "invalid-phone" };
+        case "ORDER_LOOKUP_RATE_LIMITED":
+            return { status: "rate-limited", retryAfterSeconds: result.domainError.retryAfterSeconds ?? null };
+        default:
+            return { status: "failed" };
+    }
+}

package/dist/routes.d.ts

@@ -26,6 +26,8 @@ export declare const STOREFRONT_PAGE_PATHS: {
     readonly landing: "/lp/:slug";
     readonly checkout: "/checkout";
     readonly thankYou: "/thank-you";
+    /** Where a shopper follows an order by its number and phone; `?order=<number>` fills the number in. */
+    readonly trackOrder: "/track-order";
 };
 /** What a storefront URL means. */
 export type StorefrontPageType = keyof typeof STOREFRONT_PAGE_PATHS;

package/dist/routes.js

@@ -9,6 +9,8 @@ export const STOREFRONT_PAGE_PATHS = {
     landing: "/lp/:slug",
     checkout: "/checkout",
     thankYou: "/thank-you",
+    /** Where a shopper follows an order by its number and phone; `?order=<number>` fills the number in. */
+    trackOrder: "/track-order",
 };
 /**
  * The public path of a page type, its parameter encoded:
@@ -65,6 +67,7 @@ const WIDGET_SURFACE = {
     landing: "landing",
     checkout: "checkout",
     thankYou: "thankYou",
+    trackOrder: "pages",
 };
 /**
  * @deprecated Use `STOREFRONT_PAGE_PATHS` (every page type, the home and the

package/dist/store-request.d.ts

@@ -84,7 +84,7 @@ export interface NotFoundContext {
         set(options: false): void;
     };
     response: {
-        status: number;
+        status?: number | undefined;
     };
     rewrite(path: string): Promise<Response>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",