@standhigher/besttrack-page-extension 0.5.10 → 0.5.12

package/dist/index.d.ts

@@ -17,19 +17,19 @@ type SearchTab = 'order' | 'tracking';
 type TrackingNode = {
     node: string;
     description: string;
-    time: string;
+    time?: string | null;
     location: string;
     country: string;
     state: string;
     city: string;
     street: string;
-    carrier: string;
+    carrier?: string;
 };
 type RawEvent = {
     stage: string;
     sub_status: string;
     description: string;
-    time: string;
+    time?: string | null;
     location: string;
     country: string;
     state: string;
@@ -274,55 +274,142 @@ declare function buildShopifyRecommendPayload(page?: number, pageSize?: 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.
+ * 将旧 /track/query 响应映射为三套模板共用的结果模型，非零业务 code 转为 empty。
+ * 本函数只处理响应；网络重试和异常转 empty 的兼容行为由 createShopifyTrackQuery 负责。
  */
 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.
+ * 保留旧 /track/query 协议：snake_case 请求体、_t 防缓存、默认额外重试一次。
+ * 业务失败和重试耗尽均返回 empty；自定义宿主 query 若抛错，则由 Runtime 转为 error。
+ * 英文重查仍请求同一真实接口，不是退回 Mock；仅在显式开启且当前语言不是 EN 时启用。
  */
 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 ReadyToGoRuntimeState = {
+/** 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;
+
+/** 第一层历史项：保存提交的查询身份和完整结果，恢复时无需再次请求接口。 */
+type TrackingRecentQuery = {
+    mode: "tracking" | "order";
+    value: string;
+    email?: string;
+    result: TrackingPageQueryResult;
+};
+/** empty 由结果显式标记；error 表示查询回调抛错，不能仅凭缺少物流节点判断未找到。 */
+type TrackingRuntimeState = {
     phase: "idle" | "loading" | "success" | "empty" | "error";
-    result?: ReadyToGoTrackingResult;
+    result?: TrackingPageQueryResult;
     error?: string;
 };
-type ReadyToGoRuntimeProviderProps = {
+type TrackingRuntime = TrackingRuntimeState & {
+    query(request: TrackingPageQueryRequest): Promise<void>;
+    reset(): void;
+    resourceResolution?: ShopifyResourceResolution;
+    recentQueries: TrackingRecentQuery[];
+    selectedRecentIndex: number;
+    /** 仅显式点击历史记录时递增；与查询完成、包裹切换区分，供表单判断是否回填输入。 */
+    selectionRevision: number;
+    selectedShipmentIndex: number;
+    selectRecentQuery: (index: number) => void;
+    selectShipment: (index: number) => void;
+    recommendations: TrackingPageRecommendationsState;
+    autoQueryFromUrl: boolean;
+    /** 仅供宿主明确开启演示自动查询；普通页面默认等待提交或已启用的 URL 深链。 */
+    autoQueryDemo: boolean;
+    watermark?: TrackingPageWatermark;
+    /** 编辑态广告预览；正式页面的广告仍来自当前查询结果 result.ad。 */
+    adPreview?: TrackingPageAd | null;
+};
+type TrackingRuntimeProviderProps = {
     children: ReactNode;
-    /** The discriminated, host-authorized query boundary. */
+    /** 宿主已解析的 Shopify 商品/集合资源，直接供 Sales 等区块读取；Provider 不自动解析引用。 */
+    resourceResolution?: ShopifyResourceResolution;
+    /** 宿主负责鉴权的查询入口；mode 区分运单号查询与订单号加邮箱查询。 */
     query?: TrackingPageQuery;
-    /** Independent recommended-product loader; does not share tracking loading/error. */
+    /** 页面级推荐独立加载，不共用查单的 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.
-     * Recommendations still POST `/products/recommend` on mount, even if `query` is set.
+     * 未注入 query 时，通过该传输层执行原 /track/query 的请求体、防缓存、重试与结果映射。
+     * 推荐来源单独选择：未注入 queryRecommendations 时，即使已有 query，也会使用此处的
+     * post 在挂载时请求 /products/recommend；鉴权和请求地址前缀由宿主负责。
      */
     transport?: ShopifyTrackPageTransport;
-    /** When omitted, URL deep-link auto-query is on only for the Shopify Track Page `transport` path. */
+    /** 未显式指定时，仅 transport 存在且没有注入 query 的路径默认开启 URL 深链自动查询。 */
     autoQueryFromUrl?: boolean;
     /**
-     * Preview-only: query the form's demo tracking number on mount.
-     * Live storefronts must omit this so consumers still submit the form.
+     * 仅演示预览使用：挂载后查询表单初始演示运单号。
+     * 正式宿主不能依靠演示编号自动查询；真实深链自动查询由 autoQueryFromUrl 单独控制。
      */
     autoQueryDemo?: boolean;
-    /** Host-decided display state. Omitted values follow the original powered-by hide rule. */
+    /** 优先使用宿主决定的水印显隐；未提供时沿用原 powered-by 规则。 */
     watermark?: TrackingPageWatermark;
-    /** Admin-only promotion preview; live storefronts continue to use result.ad. */
+    /** 编辑态广告预览；正式页面的广告仍来自当前查询结果 result.ad。 */
     adPreview?: TrackingPageAd | null;
 };
-declare function ReadyToGoRuntimeProvider({ children, query: injectedQuery, queryRecommendations, transport, autoQueryFromUrl, autoQueryDemo, watermark, adPreview }: ReadyToGoRuntimeProviderProps): react.JSX.Element;
+/**
+ * 三套模板共用的页面状态；历史与订单结果仅保存在本 Provider 内存中。
+ * 店铺、访客授权或 Mock/Live 上下文改变时，宿主需重新挂载或更换 key；替换 query 本身不清历史。
+ */
+declare function TrackingRuntimeProvider({ children, query: injectedQuery, queryRecommendations, transport, autoQueryFromUrl, autoQueryDemo, watermark, adPreview, resourceResolution }: TrackingRuntimeProviderProps): react.JSX.Element;
+declare function useTrackingRuntime(): TrackingRuntime;
+
+type ReadyToGoTrackingStep = TrackingPageTrackingStep;
+type ReadyToGoTrackingEvent = TrackingPageTrackingEvent;
+type ReadyToGoShipment = TrackingPageShipment;
+type ReadyToGoTrackingResult = TrackingPageQueryResult;
 
 /**
  * Compatibility metadata for template-aware hosts.
@@ -364,20 +451,13 @@ declare const brandedTemplatePolicy: Readonly<{
 declare function createBrandedTemplate(): TemplateDefinition;
 declare const bestTrackBrandedExtension: PageBuilderExtension;
 
-/** Branded uses the shared, display-safe Consumer Runtime result without persisting it. */
-type BrandedRuntimeState = {
-    phase: TrackingPageRuntimePhase;
-    result?: TrackingPageQueryResult;
-    error?: string;
-};
-type BrandedRuntimeProviderProps = {
-    children: ReactNode;
-    /** 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, query: injectedQuery, watermark }: BrandedRuntimeProviderProps): react.JSX.Element;
+/**
+ * 兼容旧宿主的 Branded 导入名称，实际复用 Ready-to-go 抽出的公共 Provider/Context。
+ * 不再维护 Branded 自己的查询结果、包裹选择或推荐状态；页面上的区块共享同一份状态。
+ */
+type BrandedRuntimeState = TrackingRuntimeState;
+type BrandedRuntimeProviderProps = TrackingRuntimeProviderProps;
+declare const BrandedRuntimeProvider: typeof TrackingRuntimeProvider;
 
 declare const salesTemplatePolicy: Readonly<{
     templateId: string;
@@ -390,73 +470,13 @@ declare const salesTemplatePolicy: Readonly<{
 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;
-    result?: TrackingPageQueryResult;
-};
-type SalesRuntimeProviderProps = {
-    children: ReactNode;
-    /** 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, query: injectedQuery, watermark, resourceResolution }: SalesRuntimeProviderProps): react.JSX.Element;
+/**
+ * Sales 的旧公开名称映射到共用 Runtime，避免旧接入方改名或再包一层独立状态。
+ * 查询、历史记录、包裹选择和推荐沿用 Ready-to-go 规则；商品资源解析仍由宿主提供。
+ */
+type SalesRuntimeState = TrackingRuntimeState;
+type SalesRuntimeProviderProps = TrackingRuntimeProviderProps;
+declare const SalesRuntimeProvider: typeof TrackingRuntimeProvider;
 
 type TrackingPageUrlOptions = Readonly<{
     allowLocalhost?: boolean;
@@ -476,4 +496,4 @@ declare function ShopifyResourcePickerProvider({ browser, children }: {
 declare function ShopifyProductResourceField(props: FieldProps<unknown>): react.JSX.Element;
 declare function ShopifyCollectionResourceField(props: FieldProps<unknown>): react.JSX.Element;
 
-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 };
+export { BrandedRuntimeProvider, type BrandedRuntimeProviderProps, type BrandedRuntimeState, type Locale, TrackingRuntimeProvider as ReadyToGoRuntimeProvider, type TrackingRuntimeProviderProps as ReadyToGoRuntimeProviderProps, type TrackingRuntimeState as 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, type TrackingRecentQuery, type TrackingRuntime, TrackingRuntimeProvider, type TrackingRuntimeProviderProps, type TrackingRuntimeState, 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, useTrackingRuntime, withShopifyAppProxyPrefix, withShopifyTrackCacheBust };