@standhigher/besttrack-page-extension 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,75 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { PageBuilderExtension, TemplateDefinition } from '@standhigher/puck-page-builder/runtime';
+import { PageBuilderExtension, TemplateDefinition, FieldProps } from '@standhigher/puck-page-builder/runtime';
+
+declare const SUPPORTED_LOCALES: readonly ["EN", "ZH-HANS", "FR", "ES", "DE", "PT-BR", "IT", "ID", "VI", "TH"];
+type Locale = (typeof SUPPORTED_LOCALES)[number];
+declare function resolveInitialLocale(): Locale;
+
+type ApiResponse<T> = {
+    data: T;
+    message?: string;
+    msg?: string;
+    code?: string | number;
+};
+
+type SearchTab = 'order' | 'tracking';
+type TrackingNode = {
+    node: string;
+    description: string;
+    time: string;
+    location: string;
+    country: string;
+    state: string;
+    city: string;
+    street: string;
+    carrier: string;
+};
+type RawEvent = {
+    stage: string;
+    sub_status: string;
+    description: string;
+    time: string;
+    location: string;
+    country: string;
+    state: string;
+    city: string;
+    street: string;
+};
+type PackageItem = {
+    product_id: string;
+    variant_id: string;
+    title: string;
+    variant_title: string;
+    image_url: string;
+    quantity: number;
+};
+type EstimatedDelivery = {
+    from: string;
+    to: string;
+    source: 'carrier' | 'custom';
+    carrier_source?: string;
+    display_state: 'in_transit' | 'date_updated';
+    changed_at?: string;
+};
+type TrackMilestone = {
+    tracking_number: string;
+    nodeList: TrackingNode[];
+    rawEventList?: RawEvent[];
+    carrier: string;
+    package_items: PackageItem[];
+    estimated_delivery?: EstimatedDelivery;
+};
+type AdConfig = {
+    image_url: string;
+    link_url: string;
+};
+type TrackResponse = {
+    order_number: string;
+    mileStoneList: TrackMilestone[];
+    ad_config: AdConfig;
+    trace_id: string;
+};
 
 /**
  * Display-safe, transient data returned by a Consumer Runtime query.
@@ -16,15 +85,49 @@ type TrackingPageOrderItem = {
     imageUrl?: string;
     description?: string;
     href?: string;
+    price?: TrackingPageMoney;
 };
+/** A stable Shopify object reference stored in PageDocument props. */
+type TrackingPageResourceReference = Readonly<{
+    id: string;
+    kind: "product" | "collection" | "media";
+}>;
+type TrackingPageProductReference = TrackingPageResourceReference & {
+    kind: "product";
+};
+type TrackingPageCollectionReference = TrackingPageResourceReference & {
+    kind: "collection";
+};
+type TrackingPageMediaReference = TrackingPageResourceReference & {
+    kind: "media";
+};
+/** Values are minor currency units; formatted display strings never persist in PageDocument. */
+type TrackingPageMoney = Readonly<{
+    amount: number;
+    currencyCode: string;
+    compareAtAmount?: number;
+    startsAt?: boolean;
+}>;
 type TrackingPageRecommendation = {
     id: string;
     title: string;
     description: string;
     imageUrl?: string;
     href?: string;
-    price?: string;
+    price?: TrackingPageMoney;
 };
+/** Host callback for page-level recommendations, independent of tracking queries. */
+type TrackingPageRecommendationsQuery = () => Promise<TrackingPageRecommendation[]>;
+type TrackingPageRecommendationsState = {
+    phase: TrackingPageRuntimePhase;
+    items: TrackingPageRecommendation[];
+};
+/** Dynamic merchant promotion returned by the trusted storefront host. */
+type TrackingPageAd = Readonly<{
+    imageUrl: string;
+    href?: string;
+    alt?: string;
+}>;
 type TrackingPageTrackingStep = {
     id: string;
     label: string;
@@ -47,12 +150,14 @@ type TrackingPageShipment = {
     carrier?: string;
     latestEvent?: string;
     updatedAt?: string;
-    deliveryAddress?: string;
+    /** City/region-level destination only. Never include a street address or contact data. */
+    destination?: string;
     estimatedDelivery?: string;
     progress?: TrackingPageTrackingStep[];
     events?: TrackingPageTrackingEvent[];
     orderItems?: TrackingPageOrderItem[];
     recommendations?: TrackingPageRecommendation[];
+    ad?: TrackingPageAd;
 };
 type TrackingPageQueryResult = {
     /** `empty` is a successful query with no customer-visible tracking result. */
@@ -62,38 +167,192 @@ type TrackingPageQueryResult = {
     carrier?: string;
     latestEvent?: string;
     updatedAt?: string;
-    deliveryAddress?: string;
+    /** City/region-level destination only. Never include a street address or contact data. */
+    destination?: string;
+    transitDuration?: string;
+    orderNumber?: string;
     estimatedDelivery?: string;
     progress?: TrackingPageTrackingStep[];
     events?: TrackingPageTrackingEvent[];
     orderItems?: TrackingPageOrderItem[];
     recommendations?: TrackingPageRecommendation[];
+    ad?: TrackingPageAd;
     shipments?: TrackingPageShipment[];
 };
-/** The UI receives an injected function; it never knows a Go endpoint or credential. */
-type TrackingPageQuery = (trackingNumber: string) => Promise<TrackingPageQueryResult>;
+/** A carrier lookup. The browser only supplies the display-safe identifier. */
+type TrackingPageTrackingQueryRequest = {
+    mode: "tracking";
+    trackingNumber: string;
+};
+/** An order lookup always carries both values; hosts must authorize it separately. */
+type TrackingPageOrderQueryRequest = {
+    mode: "order";
+    orderNumber: string;
+    email: string;
+};
+/**
+ * The injected host boundary. It deliberately contains no endpoint, token,
+ * tenant, or PageDocument data. The host owns authorization and transport.
+ */
+type TrackingPageQueryRequest = TrackingPageTrackingQueryRequest | TrackingPageOrderQueryRequest;
+type TrackingPageQuery = (request: TrackingPageQueryRequest) => Promise<TrackingPageQueryResult>;
+/** Host-decided display state. This package never derives entitlement status. */
+type TrackingPageWatermark = Readonly<{
+    visible: boolean;
+    label?: string;
+}>;
 type TrackingPageRuntimePhase = "idle" | "loading" | "success" | "empty" | "error";
+/** PRD input rules; hosts must validate again before reaching any upstream. */
+declare function isValidTrackingNumber(value: string): boolean;
+declare function isValidOrderNumber(value: string): boolean;
+declare function isValidOrderEmail(value: string): boolean;
 declare function isEmptyTrackingPageResult(result: TrackingPageQueryResult): boolean;
+declare function isTrackingPageResourceReference(value: unknown, kind?: TrackingPageResourceReference["kind"]): value is TrackingPageResourceReference;
+declare function formatTrackingPageMoney(value: TrackingPageMoney, locale?: string): {
+    amount: string;
+    compareAt: string | undefined;
+    startsAt: boolean;
+} | undefined;
+
+declare function syncTrackingQueryToUrl(type: SearchTab, value: string, contactValue?: string): void;
+type TrackingQueryLocationState = {
+    tab: SearchTab;
+    trackingNumber: string;
+    orderNumber: string;
+    email: string;
+    canAutoQuery: boolean;
+};
+declare function readTrackingQueryLocationState(search?: string, hash?: string): TrackingQueryLocationState;
+declare function readTrackingQueryFromLocation(search?: string, hash?: string): TrackingPageQueryRequest | undefined;
+
+/** Same hide rule as the original Shopify Track Page Home screen. */
+declare function shouldHidePoweredBy(targetWindow?: Window): boolean;
+
+declare const SHOPIFY_TRACK_QUERY_PATH = "/track/query";
+declare const SHOPIFY_RECOMMEND_PATH = "/products/recommend";
+type ShopifyTrackApiResponse<T> = ApiResponse<T>;
+/** Host-owned POST. The package never stores credentials or chooses the App Proxy prefix. */
+type ShopifyTrackPagePost = <T>(url: string, body?: Record<string, unknown>) => Promise<ShopifyTrackApiResponse<T>>;
+type ShopifyTrackPageTransport = {
+    post: ShopifyTrackPagePost;
+    /** Static locale or the original page resolver (`?lang=` then `bestrack_locale`). */
+    locale?: Locale | (() => Locale);
+    /** Original locale-switch path only: retry the lookup in English after a miss or throw. */
+    fallbackToEnglish?: boolean;
+    retries?: number;
+};
+declare function resolveShopifyTrackQueryLocale(locale?: Locale | (() => Locale)): "EN" | "ZH-HANS" | "FR" | "ES" | "DE" | "PT-BR" | "IT" | "ID" | "VI" | "TH";
+/**
+ * Prefix a Track Page path the way `withAppProxyPrefix` did. The host still
+ * chooses the prefix (`/apps/bestrack` or the storefront basename).
+ */
+declare function withShopifyAppProxyPrefix(path: string, prefix: string): string;
+type ShopifyRecommendProduct = {
+    id: string;
+    title: string;
+    handle?: string;
+    onlineStoreUrl?: string | null;
+    featuredImage?: {
+        url?: string;
+        altText?: string | null;
+    } | null;
+    price?: string;
+    variants?: Array<{
+        price?: string;
+    }> | null;
+};
+/** Append `_t=Date.now()` so storefront and App Proxy caches cannot reuse a previous lookup. */
+declare function withShopifyTrackCacheBust(url: string, now?: number): string;
+declare function buildShopifyTrackQueryPayload(request: TrackingPageQueryRequest, locale?: Locale): {
+    readonly order_number: string;
+    readonly email: string;
+    readonly tracking_number: string;
+    readonly lang: "EN" | "ZH-HANS" | "FR" | "ES" | "DE" | "PT-BR" | "IT" | "ID" | "VI" | "TH";
+};
+declare function buildShopifyRecommendPayload(page?: number, pageSize?: number): {
+    readonly page: number;
+    readonly page_size: number;
+};
+/**
+ * Convert a legacy `/track/query` envelope into the display-safe runtime result.
+ * A non-zero business `code` becomes `outcome: "empty"`. Network failures must
+ * still throw so the template can keep them distinct from a missing order.
+ */
+declare function mapShopifyTrackQueryResponse(response: ShopifyTrackApiResponse<TrackResponse | null | undefined>, request: TrackingPageQueryRequest, locale?: Locale): TrackingPageQueryResult;
+declare function mapShopifyRecommendationsResponse(response: ShopifyTrackApiResponse<{
+    products?: ShopifyRecommendProduct[];
+} | null | undefined>): TrackingPageRecommendation[];
+/**
+ * Original `/track/query` lookup: snake_case body, `_t` cache-bust, one retry,
+ * and `code !== 0` or exhausted throws become a missing-order result.
+ */
+declare function createShopifyTrackQuery(transport: ShopifyTrackPageTransport): TrackingPageQuery;
+declare function createShopifyRecommendationsQuery(post: ShopifyTrackPagePost): TrackingPageRecommendationsQuery;
 
 type ReadyToGoTrackingStep = TrackingPageTrackingStep;
 type ReadyToGoTrackingEvent = TrackingPageTrackingEvent;
 type ReadyToGoShipment = TrackingPageShipment;
 type ReadyToGoTrackingResult = TrackingPageQueryResult;
-type ReadyToGoTrackingQuery = TrackingPageQuery;
 type ReadyToGoRuntimeState = {
-    phase: "idle" | "loading" | "success" | "error";
+    phase: "idle" | "loading" | "success" | "empty" | "error";
     result?: ReadyToGoTrackingResult;
     error?: string;
 };
 type ReadyToGoRuntimeProviderProps = {
     children: ReactNode;
-    queryTracking?: ReadyToGoTrackingQuery;
+    /** The discriminated, host-authorized query boundary. */
+    query?: TrackingPageQuery;
+    /** Independent recommended-product loader; does not share tracking loading/error. */
+    queryRecommendations?: TrackingPageRecommendationsQuery;
+    /**
+     * Shopify Track Page live transport. When `query` is omitted, lookups use the
+     * original `/track/query` body, `_t` cache-bust, retry, and mapping rules.
+     */
+    transport?: ShopifyTrackPageTransport;
+    /** When omitted, URL deep-link auto-query is on only for the Shopify Track Page `transport` path. */
+    autoQueryFromUrl?: boolean;
+    /** Host-decided display state. Omitted values follow the original powered-by hide rule. */
+    watermark?: TrackingPageWatermark;
 };
-declare function ReadyToGoRuntimeProvider({ children, queryTracking }: ReadyToGoRuntimeProviderProps): react.JSX.Element;
+declare function ReadyToGoRuntimeProvider({ children, query: injectedQuery, queryRecommendations, transport, autoQueryFromUrl, watermark }: ReadyToGoRuntimeProviderProps): react.JSX.Element;
 
+/**
+ * Compatibility metadata for template-aware hosts.
+ *
+ * Block cardinality and deletion are now enforced by the matching native
+ * `BlockDefinition.policy` declarations. This remains an ergonomic template
+ * overview for hosts that need to present the default composition.
+ */
+type TemplateBlockPolicy = Readonly<{
+    blockType: string;
+    singleton: boolean;
+    deletable: boolean;
+}>;
+type TemplatePolicy = Readonly<{
+    templateId: string;
+    displayName: string;
+    defaultBlockOrder: readonly string[];
+    blocks: readonly TemplateBlockPolicy[];
+    enforcement: "core-block-policy";
+}>;
+
+declare const readyToGoTemplatePolicy: Readonly<{
+    templateId: string;
+    displayName: string;
+    defaultBlockOrder: readonly string[];
+    blocks: readonly TemplateBlockPolicy[];
+    enforcement: "core-block-policy";
+}>;
 declare function createReadyToGoTemplate(): TemplateDefinition;
 declare const bestTrackPageExtension: PageBuilderExtension;
 
+declare const brandedTemplatePolicy: Readonly<{
+    templateId: string;
+    displayName: string;
+    defaultBlockOrder: readonly string[];
+    blocks: readonly TemplateBlockPolicy[];
+    enforcement: "core-block-policy";
+}>;
 declare function createBrandedTemplate(): TemplateDefinition;
 declare const bestTrackBrandedExtension: PageBuilderExtension;
 
@@ -105,14 +364,75 @@ type BrandedRuntimeState = {
 };
 type BrandedRuntimeProviderProps = {
     children: ReactNode;
-    queryTracking: TrackingPageQuery;
+    /** The discriminated, host-authorized request contract. */
+    query?: TrackingPageQuery;
+    /** Host-decided display state; no entitlement checks happen in this package. */
+    watermark?: TrackingPageWatermark;
 };
-declare function BrandedRuntimeProvider({ children, queryTracking }: BrandedRuntimeProviderProps): react.JSX.Element;
+declare function BrandedRuntimeProvider({ children, query: injectedQuery, watermark }: BrandedRuntimeProviderProps): react.JSX.Element;
 
-/** Stable Sales v1 document and block IDs are intentionally retained for published-page compatibility. */
+declare const salesTemplatePolicy: Readonly<{
+    templateId: string;
+    displayName: string;
+    defaultBlockOrder: readonly string[];
+    blocks: readonly TemplateBlockPolicy[];
+    enforcement: "core-block-policy";
+}>;
+/** Sales v3 uses stable IDs and JSON-only Shopify resource references in new documents. */
 declare function createSalesTemplate(): TemplateDefinition;
 declare const bestTrackSalesExtension: PageBuilderExtension;
 
+/** The JSON-only Shopify reference that may be persisted in PageDocument props. */
+type ShopifyResourceReference = Readonly<{
+    id: string;
+    kind: "product" | "collection";
+    title: string;
+    handle?: string;
+}>;
+type ShopifyResourceKind = ShopifyResourceReference["kind"];
+type ShopifyResourceSearchInput = Readonly<{
+    kinds: readonly ShopifyResourceKind[];
+    query: string;
+    cursor?: string;
+    limit: number;
+}>;
+type ShopifyResourceSearchPage = Readonly<{
+    items: readonly ShopifyResourceReference[];
+    nextCursor?: string;
+}>;
+/** Injected by the authenticated Admin host; it owns browse, search, pagination, and authorization. */
+type ShopifyResourceBrowser = {
+    search(input: ShopifyResourceSearchInput): Promise<ShopifyResourceSearchPage>;
+};
+declare function isShopifyResourceReference(value: unknown, kind?: ShopifyResourceKind): value is ShopifyResourceReference;
+type ShopifyResourceAvailability = "available" | "sold-out" | "unavailable" | "unknown";
+/** A trusted Runtime may add these values transiently; they must never be saved back to PageDocument. */
+type ShopifyResolvedResource = ShopifyResourceReference & Readonly<{
+    status: "resolved";
+    href?: string;
+    imageUrl?: string;
+    availability: ShopifyResourceAvailability;
+}>;
+type ShopifyResourceResolutionError = Readonly<{
+    code: "invalid-reference" | "missing" | "unavailable" | "resolution-failed";
+}>;
+type ShopifyResourceResolution = Readonly<{
+    resources: Readonly<Record<string, ShopifyResolvedResource>>;
+    errors: Readonly<Record<string, ShopifyResourceResolutionError>>;
+}>;
+/** Server-side host contract. The extension never contacts Shopify or supplies an implementation. */
+type ShopifyResourceResolver = {
+    resolve(input: {
+        references: readonly ShopifyResourceReference[];
+    }): Promise<readonly ShopifyResolvedResource[]>;
+};
+/** Validates and normalizes a host response; a live resolution failure never becomes mock data. */
+declare function resolveShopifyResources(references: readonly unknown[], resolver: ShopifyResourceResolver): Promise<ShopifyResourceResolution>;
+declare function getResolvedShopifyResource(reference: unknown, resolution?: ShopifyResourceResolution): ShopifyResolvedResource | undefined;
+declare function getShopifyResourceResolutionError(reference: unknown, resolution?: ShopifyResourceResolution): Readonly<{
+    code: "invalid-reference" | "missing" | "unavailable" | "resolution-failed";
+}> | undefined;
+
 /** Transient, consumer-safe state. The host error is deliberately never retained for display. */
 type SalesRuntimeState = {
     phase: TrackingPageRuntimePhase;
@@ -120,9 +440,32 @@ type SalesRuntimeState = {
 };
 type SalesRuntimeProviderProps = {
     children: ReactNode;
-    queryTracking: TrackingPageQuery;
+    /** The discriminated, host-authorized request contract. */
+    query?: TrackingPageQuery;
+    /** Host-decided display state; no entitlement checks happen in this package. */
+    watermark?: TrackingPageWatermark;
+    /** Server-resolved and transient; this provider never resolves Shopify resources. */
+    resourceResolution?: ShopifyResourceResolution;
 };
 /** The host injects a validated query; Sales never calls a DataSource itself. */
-declare function SalesRuntimeProvider({ children, queryTracking }: SalesRuntimeProviderProps): react.JSX.Element;
+declare function SalesRuntimeProvider({ children, query: injectedQuery, watermark, resourceResolution }: SalesRuntimeProviderProps): react.JSX.Element;
+
+type TrackingPageUrlOptions = Readonly<{
+    allowLocalhost?: boolean;
+}>;
+/**
+ * Sanitizes merchant-configured URLs before they enter a rendered href or src.
+ * Production accepts public HTTPS only. HTTP is limited to an explicitly local
+ * development host and relative URLs are never part of the template protocol.
+ */
+declare function safeTrackingPageUrl(value: unknown, options?: TrackingPageUrlOptions): string | undefined;
+declare function isSafeTrackingPageUrl(value: unknown, options?: TrackingPageUrlOptions): boolean;
+
+declare function ShopifyResourcePickerProvider({ browser, children }: {
+    browser?: ShopifyResourceBrowser;
+    children: ReactNode;
+}): react.JSX.Element;
+declare function ShopifyProductResourceField(props: FieldProps<unknown>): react.JSX.Element;
+declare function ShopifyCollectionResourceField(props: FieldProps<unknown>): 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, type TrackingPageOrderItem, type TrackingPageQuery, type TrackingPageQueryResult, type TrackingPageRecommendation, type TrackingPageRuntimePhase, type TrackingPageShipment, type TrackingPageTrackingEvent, type TrackingPageTrackingStep, bestTrackBrandedExtension, bestTrackPageExtension, bestTrackSalesExtension, createBrandedTemplate, createReadyToGoTemplate, createSalesTemplate, isEmptyTrackingPageResult };
+export { BrandedRuntimeProvider, type BrandedRuntimeProviderProps, type BrandedRuntimeState, type Locale, ReadyToGoRuntimeProvider, type ReadyToGoRuntimeProviderProps, type ReadyToGoRuntimeState, type ReadyToGoShipment, type ReadyToGoTrackingEvent, type ReadyToGoTrackingResult, type ReadyToGoTrackingStep, SHOPIFY_RECOMMEND_PATH, SHOPIFY_TRACK_QUERY_PATH, SalesRuntimeProvider, type SalesRuntimeProviderProps, type SalesRuntimeState, ShopifyCollectionResourceField, ShopifyProductResourceField, type ShopifyResolvedResource, type ShopifyResourceAvailability, type ShopifyResourceBrowser, type ShopifyResourceKind, ShopifyResourcePickerProvider, type ShopifyResourceReference, type ShopifyResourceResolution, type ShopifyResourceResolutionError, type ShopifyResourceResolver, type ShopifyResourceSearchInput, type ShopifyResourceSearchPage, type ShopifyTrackPageTransport, type TemplateBlockPolicy, type TemplatePolicy, type TrackingPageAd, type TrackingPageCollectionReference, type TrackingPageMediaReference, type TrackingPageMoney, type TrackingPageOrderItem, type TrackingPageOrderQueryRequest, type TrackingPageProductReference, type TrackingPageQuery, type TrackingPageQueryRequest, type TrackingPageQueryResult, type TrackingPageRecommendation, type TrackingPageRecommendationsQuery, type TrackingPageRecommendationsState, type TrackingPageResourceReference, type TrackingPageRuntimePhase, type TrackingPageShipment, type TrackingPageTrackingEvent, type TrackingPageTrackingQueryRequest, type TrackingPageTrackingStep, type TrackingPageUrlOptions, type TrackingPageWatermark, bestTrackBrandedExtension, bestTrackPageExtension, bestTrackSalesExtension, brandedTemplatePolicy, buildShopifyRecommendPayload, buildShopifyTrackQueryPayload, createBrandedTemplate, createReadyToGoTemplate, createSalesTemplate, createShopifyRecommendationsQuery, createShopifyTrackQuery, formatTrackingPageMoney, getResolvedShopifyResource, getShopifyResourceResolutionError, isEmptyTrackingPageResult, isSafeTrackingPageUrl, isShopifyResourceReference, isTrackingPageResourceReference, isValidOrderEmail, isValidOrderNumber, isValidTrackingNumber, mapShopifyRecommendationsResponse, mapShopifyTrackQueryResponse, readTrackingQueryFromLocation, readTrackingQueryLocationState, readyToGoTemplatePolicy, resolveInitialLocale, resolveShopifyResources, resolveShopifyTrackQueryLocale, safeTrackingPageUrl, salesTemplatePolicy, shouldHidePoweredBy, syncTrackingQueryToUrl, withShopifyAppProxyPrefix, withShopifyTrackCacheBust };