@standhigher/besttrack-page-extension 0.3.0 → 0.4.0

package/README.md

@@ -1,34 +1,71 @@
 # @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
-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. 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.
+This package provides the built-in Ready-to-go, Branded, and Sales tracking
+templates for `@standhigher/puck-page-builder`. Each template has stable
+namespaced v1 block IDs, default block order, theme tokens, and exported
+`TemplatePolicy` metadata. All default blocks are singleton. Protected
+query/structure blocks now use the core `BlockDefinition.policy` contract
+(`required`, `singleton`, and `allowDelete: false`), which the editor enforces.
+
+## Query provider
+
+Branded and Sales still receive a host-owned `TrackingPageQuery` through `query`.
+Ready-to-go storefront pages that keep the original Shopify Track Page backend
+should inject `transport` instead of inventing a new request body:
+
+```tsx
+<ReadyToGoRuntimeProvider
+  transport={{
+    post: (url, body) => apiPost(withShopifyAppProxyPrefix(url, APP_PROXY_PREFIX), body)
+  }}
+>
+  <WebRenderer document={document} registry={registry} />
+</ReadyToGoRuntimeProvider>
+```
+
+That path reuses the original lookup: `POST /track/query?_t=`, snake_case
+`{ order_number, email, tracking_number, lang }`, one retry, independent
+`POST /products/recommend` with `{ page, page_size }`, and the original
+progress / shipping / empty-state mapping. The host only supplies fetch,
+App Proxy prefix, and credentials.
+
+Branded and Sales keep the discriminated `query` callback:
+
+```tsx
+const query: TrackingPageQuery = async (request) => {
+  if (request.mode === "tracking") {
+    return serverAuthorizedTrackingLookup(request.trackingNumber);
+  }
+  return serverAuthorizedOrderLookup(request.orderNumber, request.email);
+};
+
+<SalesRuntimeProvider query={query} watermark={{ visible: true }}>
+  <WebRenderer document={document} registry={registry} />
+</SalesRuntimeProvider>
+```
+
+`TrackingPageQueryRequest` is either `{ mode: "tracking", trackingNumber }`
+or `{ mode: "order", orderNumber, email }`. Ready-to-go matches the original
+Track Page and only requires non-empty trimmed fields. Branded and Sales still
+perform local PRD format checks. The host must authorize again on the server.
+A host must not submit an order number through the tracking-number mode.
+
+Branded and Sales render a two-tab query card on the Hero’s right edge at
+desktop widths and as a single full-width card on narrow screens. Each tab
+retains its own input. Loading, error, empty, and replacement results remain
+inside the scrollable query card; successful requests scroll the result into
+view. The package never stores tokens and never writes a query result into a
+`PageDocument`.
+
+## Watermarks and data safety
+
+The optional `watermark` provider prop is a host override. Ready-to-go uses the
+original powered-by hide rule when it is omitted. Branded and Sales only render
+`watermark.visible` and its optional label; they do not infer entitlement.
+Query results and watermark state are transient.
+
+Document props and bindings must remain JSON-only and must not contain a token,
+secret, customer order data, email address, or live query result. Merchant
+resources use stable Shopify IDs; product prices and availability are Runtime
+data. Production URLs must be public HTTPS URLs. Missing display data and
+unsafe resource URLs render controlled fallbacks.

package/dist/chunk-KD7KFFFK.js

@@ -0,0 +1,127 @@
+// src/tracking-page-runtime.ts
+function isValidTrackingNumber(value) {
+  return /^[A-Za-z0-9_-]{6,64}$/.test(value);
+}
+function isValidOrderNumber(value) {
+  return /^\S{1,64}$/.test(value);
+}
+function isValidOrderEmail(value) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) && value.length <= 254;
+}
+function isEmptyTrackingPageResult(result) {
+  return result.outcome === "empty";
+}
+function isTrackingPageResourceReference(value, kind) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value;
+  return typeof candidate.id === "string" && candidate.id.startsWith("gid://shopify/") && (candidate.kind === "product" || candidate.kind === "collection" || candidate.kind === "media") && (kind === void 0 || candidate.kind === kind);
+}
+function formatTrackingPageMoney(value, locale = "en-US") {
+  if (!Number.isInteger(value.amount) || !/^[A-Z]{3}$/.test(value.currencyCode)) return void 0;
+  try {
+    const amount = new Intl.NumberFormat(locale, { style: "currency", currency: value.currencyCode }).format(value.amount / 100);
+    const compareAt = value.compareAtAmount !== void 0 && Number.isInteger(value.compareAtAmount) && value.compareAtAmount > value.amount ? new Intl.NumberFormat(locale, { style: "currency", currency: value.currencyCode }).format(value.compareAtAmount / 100) : void 0;
+    return { amount, compareAt, startsAt: value.startsAt === true };
+  } catch {
+    return void 0;
+  }
+}
+
+// src/tracking-page-url.ts
+function hasControlCharacter(value) {
+  return [...value].some((character) => character.charCodeAt(0) < 32);
+}
+function isLocalDevelopmentHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+function allowsLocalhostByDefault() {
+  return typeof window !== "undefined" && isLocalDevelopmentHost(window.location.hostname);
+}
+function safeTrackingPageUrl(value, options = {}) {
+  if (typeof value !== "string" || !value || value.trim() !== value || hasControlCharacter(value)) return void 0;
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) return void 0;
+    if (url.protocol === "https:" && !isLocalDevelopmentHost(url.hostname)) return url.toString();
+    if (url.protocol === "http:" && isLocalDevelopmentHost(url.hostname) && (options.allowLocalhost ?? allowsLocalhostByDefault())) return url.toString();
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isSafeTrackingPageUrl(value, options) {
+  return safeTrackingPageUrl(value, options) !== void 0;
+}
+
+// src/shopify-resource-contract.ts
+var resourcePattern = /^gid:\/\/shopify\/(Product|Collection)\/[1-9]\d*$/;
+function isShopifyResourceReference(value, kind) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value;
+  const match = typeof candidate.id === "string" ? resourcePattern.exec(candidate.id) : null;
+  const expectedKind = match?.[1] === "Product" ? "product" : match?.[1] === "Collection" ? "collection" : void 0;
+  return candidate.kind === expectedKind && expectedKind !== void 0 && (kind === void 0 || expectedKind === kind) && typeof candidate.title === "string" && Boolean(candidate.title.trim()) && candidate.title.length <= 160 && (candidate.handle === void 0 || typeof candidate.handle === "string" && /^[a-z0-9][a-z0-9-]{0,254}$/i.test(candidate.handle));
+}
+function resourceKey(reference) {
+  return `${reference.kind}:${reference.id}`;
+}
+function isResolvedResource(value) {
+  if (!isShopifyResourceReference(value)) return false;
+  const candidate = value;
+  return candidate.status === "resolved" && (candidate.availability === "available" || candidate.availability === "sold-out" || candidate.availability === "unavailable" || candidate.availability === "unknown") && (candidate.href === void 0 || typeof candidate.href === "string") && (candidate.imageUrl === void 0 || typeof candidate.imageUrl === "string");
+}
+async function resolveShopifyResources(references, resolver) {
+  const resources = {};
+  const errors = {};
+  const valid = /* @__PURE__ */ new Map();
+  references.forEach((reference, index) => {
+    if (!isShopifyResourceReference(reference)) {
+      errors[`invalid:${index}`] = { code: "invalid-reference" };
+      return;
+    }
+    valid.set(resourceKey(reference), reference);
+  });
+  if (!valid.size) return { resources, errors };
+  let resolved;
+  try {
+    resolved = await resolver.resolve({ references: [...valid.values()] });
+  } catch {
+    valid.forEach((reference) => {
+      errors[resourceKey(reference)] = { code: "resolution-failed" };
+    });
+    return { resources, errors };
+  }
+  resolved.forEach((candidate) => {
+    if (!isResolvedResource(candidate)) return;
+    const key = resourceKey(candidate);
+    if (!valid.has(key)) return;
+    const href = safeTrackingPageUrl(candidate.href);
+    const imageUrl = safeTrackingPageUrl(candidate.imageUrl);
+    resources[key] = { id: candidate.id, kind: candidate.kind, title: candidate.title.trim(), ...candidate.handle ? { handle: candidate.handle } : {}, status: "resolved", availability: candidate.availability, ...href ? { href } : {}, ...imageUrl ? { imageUrl } : {} };
+  });
+  valid.forEach((reference, key) => {
+    if (!resources[key]) errors[key] = { code: "missing" };
+  });
+  return { resources, errors };
+}
+function getResolvedShopifyResource(reference, resolution) {
+  return isShopifyResourceReference(reference) ? resolution?.resources[resourceKey(reference)] : void 0;
+}
+function getShopifyResourceResolutionError(reference, resolution) {
+  return isShopifyResourceReference(reference) ? resolution?.errors[resourceKey(reference)] : void 0;
+}
+
+export {
+  isValidTrackingNumber,
+  isValidOrderNumber,
+  isValidOrderEmail,
+  isEmptyTrackingPageResult,
+  isTrackingPageResourceReference,
+  formatTrackingPageMoney,
+  safeTrackingPageUrl,
+  isSafeTrackingPageUrl,
+  isShopifyResourceReference,
+  resolveShopifyResources,
+  getResolvedShopifyResource,
+  getShopifyResourceResolutionError
+};