@shop-on/theme-server 0.5.0 → 0.7.0

package/dist/search.d.ts

@@ -37,6 +37,9 @@ type FetchProductSearchPageInput = {
   includeOptions?: boolean;
   includeVariants?: boolean;
   locale?: string;
+  /** Storefront-visible metafields (`"namespace.key"`) each card carries, for
+   * the `closest_product_metafield` sources bound on it. Omitted ⇒ none. */
+  metafieldKeys?: readonly string[];
 };
 /** Server-driven /search page. Returns `null` for blank query (caller
  * route renders the empty-prompt UI) or on GraphQL error. Uncached because

package/dist/search.js

@@ -1,5 +1,6 @@
 import { graphql, request } from "./graphql.js";
 import { toFileInfo } from "./files.js";
+import { metafieldKeysVariables } from "./product.js";
 import { CollectionImageFragment, CollectionProductNodeFragment, toCollectionProduct, toPriceBounds, variantsVariable } from "./collection.js";
 //#region src/search.ts
 const SEARCH_PAGE_SIZE = 24;
@@ -10,6 +11,9 @@ const FetchProductSearchPageQuery = graphql(`
       $mediaFirst: Int!
       $includeOptions: Boolean!
       $includeVariants: Boolean = false
+      $withMetafields: Boolean = false
+      $metafieldFirst: Int = 0
+      $metafieldKeys: [MetafieldKeyInput!] = []
       $after: String
       $filter: CollectionProductFilterInput
       $sort: ProductSearchSortEnum
@@ -81,6 +85,7 @@ const fetchProductSearchPage = async (data) => {
 			mediaFirst,
 			includeOptions,
 			...variantsVariable(data.includeVariants),
+			...metafieldKeysVariables(data.metafieldKeys),
 			after: after ?? null,
 			filter: filter ?? null,
 			sort: sort ?? null

package/dist/structured-data.d.ts

@@ -0,0 +1,47 @@
+import { ResultOf } from "./graphql.js";
+import { OrganizationSchemaSource, ReturnPolicySchemaSource } from "@shop-on/theme-runtime/template-types";
+//#region src/structured-data.d.ts
+declare const ShopStructuredDataQuery: import("gql.tada").TadaDocumentNode<{
+  shop: {
+    branding: {
+      logo: {
+        url: string | null;
+      } | null;
+    } | null;
+    countryCode: string | null;
+    refundPolicy: {
+      url: string;
+    } | null;
+    returnPolicy: {
+      configured: boolean;
+      flatRateAmount: {
+        amount: string;
+        currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
+      } | null;
+      restockingFeePercentage: number | null;
+      returnShippingCost: "CUSTOMER_PROVIDED" | "FLAT_RATE" | "FREE";
+      returnWindowDays: number | null;
+    };
+  } | null;
+}, {}, void>;
+type ShopRecord = NonNullable<ResultOf<typeof ShopStructuredDataQuery>["shop"]>;
+/**
+ * The shop's return policy as schema.org reads it, for one product or (with
+ * `finalSale` false) the shop as a whole. Undefined until the merchant saves a
+ * policy: the defaults an unconfigured shop reads back ("unlimited window,
+ * free returns") are no promise the merchant made, and publishing them would
+ * tell Google and every agent exactly that. Also undefined without a country,
+ * which Google requires.
+ */
+export declare function returnPolicySource(shop: ShopRecord, { finalSale, base }: {
+  finalSale: boolean;
+  base: string;
+}): ReturnPolicySchemaSource | undefined;
+/** A product's return policy: the shop's, or "not permitted" when the
+ * product is final sale (`ShopProduct.finalSale`). */
+export declare function fetchProductReturnPolicy(finalSale: boolean, base: string): Promise<ReturnPolicySchemaSource | undefined>;
+/** The homepage's Organization node. Undefined without a name or origin —
+ * schema.org needs both and the homepage then emits no node at all. */
+export declare function fetchOrganizationSchema(name: string, base: string): Promise<OrganizationSchemaSource | undefined>;
+//#endregion
+export {};

package/dist/structured-data.js

@@ -0,0 +1,110 @@
+import { memoTTL } from "./cache.js";
+import { graphql, request } from "./graphql.js";
+import { getContentVersion } from "./content-version.js";
+//#region src/structured-data.ts
+const ShopStructuredDataQuery = graphql(`
+  query StorefrontShopStructuredData {
+    shop {
+      countryCode
+      branding {
+        logo {
+          url
+        }
+      }
+      refundPolicy {
+        url
+      }
+      returnPolicy {
+        configured
+        returnWindowDays
+        restockingFeePercentage
+        returnShippingCost
+        flatRateAmount {
+          amount
+          currencyCode
+        }
+      }
+    }
+  }
+`);
+const fetchShopRecord = memoTTL(async () => (await request(ShopStructuredDataQuery)).shop ?? null, {
+	key: () => "",
+	version: getContentVersion
+});
+async function safeShopRecord() {
+	try {
+		return await fetchShopRecord();
+	} catch (err) {
+		console.warn("[structured-data] shop fetch failed:", err);
+		return null;
+	}
+}
+const FEES = {
+	FREE: "FreeReturn",
+	CUSTOMER_PROVIDED: "ReturnFeesCustomerResponsibility",
+	FLAT_RATE: "ReturnShippingFees"
+};
+/**
+* The shop's return policy as schema.org reads it, for one product or (with
+* `finalSale` false) the shop as a whole. Undefined until the merchant saves a
+* policy: the defaults an unconfigured shop reads back ("unlimited window,
+* free returns") are no promise the merchant made, and publishing them would
+* tell Google and every agent exactly that. Also undefined without a country,
+* which Google requires.
+*/
+function returnPolicySource(shop, { finalSale, base }) {
+	const policy = shop.returnPolicy;
+	if (!policy.configured || !shop.countryCode) return void 0;
+	const url = shop.refundPolicy && base ? `${base}${shop.refundPolicy.url}` : void 0;
+	const country = shop.countryCode;
+	if (finalSale) return {
+		country,
+		category: "NotPermitted",
+		...url ? { url } : {}
+	};
+	const days = policy.returnWindowDays;
+	const fee = policy.flatRateAmount;
+	const restocking = policy.restockingFeePercentage;
+	return {
+		country,
+		...days ? {
+			category: "FiniteReturnWindow",
+			days
+		} : { category: "UnlimitedWindow" },
+		fees: FEES[policy.returnShippingCost],
+		...policy.returnShippingCost === "FLAT_RATE" && fee ? { shippingFee: {
+			amount: Number(fee.amount),
+			currency: fee.currencyCode
+		} } : {},
+		...restocking ? { restockingFeePercent: restocking } : {},
+		...url ? { url } : {}
+	};
+}
+/** A product's return policy: the shop's, or "not permitted" when the
+* product is final sale (`ShopProduct.finalSale`). */
+async function fetchProductReturnPolicy(finalSale, base) {
+	const shop = await safeShopRecord();
+	return shop ? returnPolicySource(shop, {
+		finalSale,
+		base
+	}) : void 0;
+}
+/** The homepage's Organization node. Undefined without a name or origin —
+* schema.org needs both and the homepage then emits no node at all. */
+async function fetchOrganizationSchema(name, base) {
+	if (!name || !base) return void 0;
+	const shop = await safeShopRecord();
+	const logo = shop?.branding?.logo?.url;
+	const returnPolicy = shop ? returnPolicySource(shop, {
+		finalSale: false,
+		base
+	}) : void 0;
+	return {
+		name,
+		url: `${base}/`,
+		...logo ? { logo } : {},
+		...returnPolicy ? { returnPolicy } : {}
+	};
+}
+//#endregion
+export { fetchOrganizationSchema, fetchProductReturnPolicy, returnPolicySource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/theme-server",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "files": [
     "dist"
@@ -51,6 +51,7 @@
     "./shop": "./dist/shop.js",
     "./shop-seo": "./dist/shop-seo.js",
     "./store-availability": "./dist/store-availability.js",
+    "./structured-data": "./dist/structured-data.js",
     "./translations": "./dist/translations.js",
     "./package.json": "./package.json"
   },
@@ -59,8 +60,8 @@
     "graphql": "17.0.2",
     "graphql-request": "7.4.0",
     "liquidjs": "10.30.0",
-    "@shop-on/customer-runtime": "0.5.0",
-    "@shop-on/theme-runtime": "0.5.0"
+    "@shop-on/theme-runtime": "0.7.0",
+    "@shop-on/customer-runtime": "0.7.0"
   },
   "devDependencies": {
     "@tanstack/react-start": "1.169.3",