@standhigher/besttrack-page-extension 0.2.0 → 0.3.0

package/README.md

@@ -1,9 +1,34 @@
 # @standhigher/besttrack-page-extension
 
 V0.7.1 adds the besttrack.branded built-in template. Its announcement, order
-query, order items, recommendations, quick links and Blog blocks use the same
-host-injected tracking query contract as Ready-to-go. Logo and content are
+query, order items, recommendations, quick links and Blog blocks use the
+shared, host-injected `TrackingPageQuery` contract. The
+`ReadyToGoTrackingQuery` name remains a compatible alias. Logo and content are
 JSON-only block props; brand colour, font and radius use the template Theme
 Tokens and may be overridden through PageDocument.theme.
 
-V0.7.0 provides the Ready-to-go built-in template: order query, shipment progress, delivery information and recommendations. Live tracking is injected by the host Runtime; this package never stores credentials or network endpoints in a `PageDocument`.
+V0.7.0 provides the Ready-to-go built-in template: order query, shipment
+progress, delivery information and recommendations. The consumer surface follows
+the Shopify Track Page layout (query card, five-step progress, shipping
+timeline, package contents and product cards) using inline styles and `--pb-*`
+Theme Tokens. Live tracking is injected by the host Runtime; this package never
+stores credentials or network endpoints in a `PageDocument`.
+
+V0.7.2 Sales uses the shared, transient `TrackingPageQuery` contract exported
+by this package. The external Go Consumer Runtime API owns live-query
+authorization and transport; Sales only receives its display-safe result and
+never falls back to mock data after a live failure.
+
+Sales keeps the stable `besttrack.sales` v1 template and seven block IDs.
+Its host must inject the query from an authorized Consumer Runtime flow; this
+package provides neither a Go client nor a BFF. The editor validates
+merchant-authored text, preview-only tracking placeholders and collection
+links, while the storefront renders only site-relative or HTTPS resource
+links. See `docs/integration/sales-template.md` and
+`docs/integration/consumer-runtime-api.md` for the host contract.
+
+New Sales pages use the `hero` visual Variant: a token-driven announcement,
+merchant HTTPS hero image and tracking-only query card. Existing `commerce`
+Variants and published v1 documents stay valid. The browser does not offer an
+order-number mode because the shared Consumer Runtime API currently accepts
+only a tracking number.

package/dist/index.d.ts

@@ -2,14 +2,22 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { PageBuilderExtension, TemplateDefinition } from '@standhigher/puck-page-builder/runtime';
 
-type ReadyToGoOrderItem = {
+/**
+ * Display-safe, transient data returned by a Consumer Runtime query.
+ *
+ * These types intentionally describe the boundary between a storefront host
+ * and the template. They are not PageDocument props and must never be saved
+ * with a draft or published document.
+ */
+type TrackingPageOrderItem = {
     id: string;
     title: string;
     quantity: number;
     imageUrl?: string;
     description?: string;
+    href?: string;
 };
-type ReadyToGoRecommendation = {
+type TrackingPageRecommendation = {
     id: string;
     title: string;
     description: string;
@@ -17,19 +25,21 @@ type ReadyToGoRecommendation = {
     href?: string;
     price?: string;
 };
-type ReadyToGoTrackingStep = {
+type TrackingPageTrackingStep = {
     id: string;
     label: string;
     state: "complete" | "current" | "upcoming";
+    date?: string;
+    icon?: "check" | "bag" | "truck" | "box";
 };
-type ReadyToGoTrackingEvent = {
+type TrackingPageTrackingEvent = {
     id: string;
     title: string;
     at?: string;
     detail?: string;
     state?: "complete" | "current" | "upcoming";
 };
-type ReadyToGoShipment = {
+type TrackingPageShipment = {
     id: string;
     label: string;
     trackingNumber?: string;
@@ -38,25 +48,38 @@ type ReadyToGoShipment = {
     latestEvent?: string;
     updatedAt?: string;
     deliveryAddress?: string;
-    progress?: ReadyToGoTrackingStep[];
-    events?: ReadyToGoTrackingEvent[];
-    orderItems?: ReadyToGoOrderItem[];
-    recommendations?: ReadyToGoRecommendation[];
+    estimatedDelivery?: string;
+    progress?: TrackingPageTrackingStep[];
+    events?: TrackingPageTrackingEvent[];
+    orderItems?: TrackingPageOrderItem[];
+    recommendations?: TrackingPageRecommendation[];
 };
-type ReadyToGoTrackingResult = {
+type TrackingPageQueryResult = {
+    /** `empty` is a successful query with no customer-visible tracking result. */
+    outcome?: "found" | "empty";
     trackingNumber: string;
     status: string;
     carrier?: string;
     latestEvent?: string;
     updatedAt?: string;
     deliveryAddress?: string;
-    progress?: ReadyToGoTrackingStep[];
-    events?: ReadyToGoTrackingEvent[];
-    orderItems?: ReadyToGoOrderItem[];
-    recommendations?: ReadyToGoRecommendation[];
-    shipments?: ReadyToGoShipment[];
+    estimatedDelivery?: string;
+    progress?: TrackingPageTrackingStep[];
+    events?: TrackingPageTrackingEvent[];
+    orderItems?: TrackingPageOrderItem[];
+    recommendations?: TrackingPageRecommendation[];
+    shipments?: TrackingPageShipment[];
 };
-type ReadyToGoTrackingQuery = (trackingNumber: string) => Promise<ReadyToGoTrackingResult>;
+/** The UI receives an injected function; it never knows a Go endpoint or credential. */
+type TrackingPageQuery = (trackingNumber: string) => Promise<TrackingPageQueryResult>;
+type TrackingPageRuntimePhase = "idle" | "loading" | "success" | "empty" | "error";
+declare function isEmptyTrackingPageResult(result: TrackingPageQueryResult): boolean;
+
+type ReadyToGoTrackingStep = TrackingPageTrackingStep;
+type ReadyToGoTrackingEvent = TrackingPageTrackingEvent;
+type ReadyToGoShipment = TrackingPageShipment;
+type ReadyToGoTrackingResult = TrackingPageQueryResult;
+type ReadyToGoTrackingQuery = TrackingPageQuery;
 type ReadyToGoRuntimeState = {
     phase: "idle" | "loading" | "success" | "error";
     result?: ReadyToGoTrackingResult;
@@ -74,31 +97,32 @@ declare const bestTrackPageExtension: PageBuilderExtension;
 declare function createBrandedTemplate(): TemplateDefinition;
 declare const bestTrackBrandedExtension: PageBuilderExtension;
 
+/** Branded uses the shared, display-safe Consumer Runtime result without persisting it. */
 type BrandedRuntimeState = {
-    phase: "idle" | "loading" | "success" | "error";
-    result?: ReadyToGoTrackingResult;
+    phase: TrackingPageRuntimePhase;
+    result?: TrackingPageQueryResult;
     error?: string;
 };
 type BrandedRuntimeProviderProps = {
     children: ReactNode;
-    queryTracking: ReadyToGoTrackingQuery;
+    queryTracking: TrackingPageQuery;
 };
 declare function BrandedRuntimeProvider({ children, queryTracking }: BrandedRuntimeProviderProps): react.JSX.Element;
 
+/** Stable Sales v1 document and block IDs are intentionally retained for published-page compatibility. */
 declare function createSalesTemplate(): TemplateDefinition;
 declare const bestTrackSalesExtension: PageBuilderExtension;
 
-type SalesPhase = "idle" | "loading" | "success" | "error";
+/** Transient, consumer-safe state. The host error is deliberately never retained for display. */
 type SalesRuntimeState = {
-    phase: SalesPhase;
-    result?: ReadyToGoTrackingResult;
-    error?: string;
+    phase: TrackingPageRuntimePhase;
+    result?: TrackingPageQueryResult;
 };
 type SalesRuntimeProviderProps = {
     children: ReactNode;
-    queryTracking: ReadyToGoTrackingQuery;
+    queryTracking: TrackingPageQuery;
 };
 /** The host injects a validated query; Sales never calls a DataSource itself. */
 declare function SalesRuntimeProvider({ children, queryTracking }: SalesRuntimeProviderProps): react.JSX.Element;
 
-export { BrandedRuntimeProvider, type BrandedRuntimeProviderProps, type BrandedRuntimeState, ReadyToGoRuntimeProvider, type ReadyToGoRuntimeProviderProps, type ReadyToGoRuntimeState, type ReadyToGoShipment, type ReadyToGoTrackingEvent, type ReadyToGoTrackingQuery, type ReadyToGoTrackingResult, type ReadyToGoTrackingStep, SalesRuntimeProvider, type SalesRuntimeProviderProps, type SalesRuntimeState, bestTrackBrandedExtension, bestTrackPageExtension, bestTrackSalesExtension, createBrandedTemplate, createReadyToGoTemplate, createSalesTemplate };
+export { BrandedRuntimeProvider, type BrandedRuntimeProviderProps, type BrandedRuntimeState, ReadyToGoRuntimeProvider, type ReadyToGoRuntimeProviderProps, type ReadyToGoRuntimeState, type ReadyToGoShipment, type ReadyToGoTrackingEvent, type ReadyToGoTrackingQuery, type ReadyToGoTrackingResult, type ReadyToGoTrackingStep, SalesRuntimeProvider, type SalesRuntimeProviderProps, type SalesRuntimeState, type TrackingPageOrderItem, type TrackingPageQuery, type TrackingPageQueryResult, type TrackingPageRecommendation, type TrackingPageRuntimePhase, type TrackingPageShipment, type TrackingPageTrackingEvent, type TrackingPageTrackingStep, bestTrackBrandedExtension, bestTrackPageExtension, bestTrackSalesExtension, createBrandedTemplate, createReadyToGoTemplate, createSalesTemplate, isEmptyTrackingPageResult };