@shop-on/theme-server 0.6.0 → 0.7.0

package/dist/graphql-env.d.ts

@@ -9309,6 +9309,18 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'returnPolicy': {
+        name: 'returnPolicy';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'OBJECT';
+            name: 'ShopReturnPolicy';
+            ofType: null;
+          };
+        };
+      };
       'seo': {
         name: 'seo';
         type: {
@@ -16538,6 +16550,18 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'finalSale': {
+        name: 'finalSale';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'SCALAR';
+            name: 'Boolean';
+            ofType: null;
+          };
+        };
+      };
       'giftCard': {
         name: 'giftCard';
         type: {
@@ -17980,6 +18004,14 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'gtin': {
+        name: 'gtin';
+        type: {
+          kind: 'SCALAR';
+          name: 'String';
+          ofType: null;
+        };
+      };
       'id': {
         name: 'id';
         type: {
@@ -18276,6 +18308,64 @@ export type introspection_types = {
       };
     };
   };
+  'ShopReturnPolicy': {
+    kind: 'OBJECT';
+    name: 'ShopReturnPolicy';
+    fields: {
+      'configured': {
+        name: 'configured';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'SCALAR';
+            name: 'Boolean';
+            ofType: null;
+          };
+        };
+      };
+      'flatRateAmount': {
+        name: 'flatRateAmount';
+        type: {
+          kind: 'OBJECT';
+          name: 'Money';
+          ofType: null;
+        };
+      };
+      'restockingFeePercentage': {
+        name: 'restockingFeePercentage';
+        type: {
+          kind: 'SCALAR';
+          name: 'Float';
+          ofType: null;
+        };
+      };
+      'returnShippingCost': {
+        name: 'returnShippingCost';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'ENUM';
+            name: 'ShopReturnShippingCostEnum';
+            ofType: null;
+          };
+        };
+      };
+      'returnWindowDays': {
+        name: 'returnWindowDays';
+        type: {
+          kind: 'SCALAR';
+          name: 'Int';
+          ofType: null;
+        };
+      };
+    };
+  };
+  'ShopReturnShippingCostEnum': {
+    name: 'ShopReturnShippingCostEnum';
+    enumValues: 'CUSTOMER_PROVIDED' | 'FLAT_RATE' | 'FREE';
+  };
   'ShopSeo': {
     kind: 'OBJECT';
     name: 'ShopSeo';

package/dist/product.d.ts

@@ -40,6 +40,8 @@ export type ProductData = {
     type: string;
     value: string;
   }>;
+  finalSale?: boolean;
+  gtin?: string | null;
 };
 export declare const BadgeTagsFragment: import("gql.tada").TadaDocumentNode<{
   tags: string[];

package/dist/product.js

@@ -196,6 +196,7 @@ const FetchProductFullQuery = graphql(`
         themeTemplate
         ...BadgeTags
         giftCard
+        finalSale
         descriptionHtml
         # Server-side plain-text projection of descriptionHtml — Rails
         # strips tags AND decodes HTML entities, which a client-side regex
@@ -207,6 +208,7 @@ const FetchProductFullQuery = graphql(`
         }
         defaultVariant {
           ...ProductVariantNode
+          gtin
         }
         options {
           ...ProductOptionNode
@@ -477,7 +479,9 @@ async function loadProductFull(handle, locale) {
 				title: p.seo.title,
 				description: p.seo.description
 			},
-			metafields: toMetafieldMap(p.metafields.nodes)
+			metafields: toMetafieldMap(p.metafields.nodes),
+			finalSale: p.finalSale,
+			gtin: p.defaultVariant.gtin ?? null
 		};
 	} catch (err) {
 		console.warn("[fetchProductFull] failed:", err);

package/dist/schema.storefront.graphql

@@ -4753,6 +4753,11 @@ type Shop implements Node {
   """
   refundPolicy: ShopPolicy
 
+  """
+  Per-shop return policy defaults. Always present — an unconfigured shop reads back the defaults.
+  """
+  returnPolicy: ShopReturnPolicy!
+
   """
   Shop-level SEO settings (homepage meta, social image, verification tokens). Null until the merchant configures it.
   """
@@ -7951,6 +7956,11 @@ type ShopProduct implements Node {
   """
   featuredMedia: FileInterface
 
+  """
+  Whether the return policy marks the whole product final sale (no returns). Resolve on one product at a time.
+  """
+  finalSale: Boolean!
+
   """
   True when this is a digital gift-card product (gift-card category + every
   variant unshipped). Powers the storefront recipient form and digital fulfillment.
@@ -8609,6 +8619,11 @@ type ShopProductVariant implements Node {
   First variant media — used as a thumbnail
   """
   featuredMedia: FileInterface
+
+  """
+  The GTIN for structured data: the one the merchant entered, else a barcode that passes the GS1 check; null otherwise.
+  """
+  gtin: String
   id: ID!
 
   """
@@ -8791,6 +8806,56 @@ type ShopProductVariantEdge {
   node: ShopProductVariant!
 }
 
+"""
+Per-shop return policy defaults. Advisory only — nothing here blocks a merchant-created return.
+"""
+type ShopReturnPolicy {
+  """
+  Whether the merchant has saved this policy. False means every value is a column default.
+  """
+  configured: Boolean!
+
+  """
+  Flat return-shipping amount in the shop currency. Null unless `returnShippingCost` is FLAT_RATE.
+  """
+  flatRateAmount: Money
+
+  """
+  Default restocking fee, 0..100. Null means no restocking fee is suggested.
+  """
+  restockingFeePercentage: Float
+
+  """
+  Who pays return shipping by default.
+  """
+  returnShippingCost: ShopReturnShippingCostEnum!
+
+  """
+  Days after shipment a buyer may return an item. Null means an unlimited window.
+  """
+  returnWindowDays: Int
+}
+
+"""
+Who pays to ship a return back, by default.
+"""
+enum ShopReturnShippingCostEnum {
+  """
+  The buyer arranges and pays for return shipping.
+  """
+  CUSTOMER_PROVIDED
+
+  """
+  A fixed amount is withheld; see `flatRateAmount`.
+  """
+  FLAT_RATE
+
+  """
+  The merchant covers return shipping.
+  """
+  FREE
+}
+
 """
 Per-shop SEO settings consumed by the storefront theme.
 """

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.6.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.6.0",
-    "@shop-on/theme-runtime": "0.6.0"
+    "@shop-on/theme-runtime": "0.7.0",
+    "@shop-on/customer-runtime": "0.7.0"
   },
   "devDependencies": {
     "@tanstack/react-start": "1.169.3",