@runwell/shopify-toolkit 0.18.0 → 0.23.0

package/modules/runwell-bundle-system/admin-metafields.json

@@ -0,0 +1,55 @@
+{
+  "$comment": "Source of truth for runwell.bundle_* product metafield definitions. Mirrors spec.md section 2.1. Read by runwell-shopify provision-metafields (when implemented) and by admin-guide.md for manual setup.",
+  "spec_ref": "_clients/capital-v/lushi/specs/bundle-system/spec.md#21-per-bundle-product-metafields",
+  "product_metafields": {
+    "namespace": "runwell",
+    "owner_type": "PRODUCT",
+    "definitions": [
+      { "key": "bundle_mode", "name": "Bundle mode", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"quantity_tiers\",\"multi_product\",\"mix_match\",\"byob\",\"subscription\"]" }] },
+      { "key": "bundle_pricing_model", "name": "Bundle pricing model", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"tier_quantity\",\"fixed_price\",\"fixed_bundle_price\",\"percent_off_subtotal\",\"dollar_off_subtotal\"]" }] },
+      { "key": "bundle_pricing_value", "name": "Bundle pricing value (JSON)", "type": "json", "description": "Shape varies by pricing_model. See spec.md section 2.2." },
+      { "key": "bundle_components", "name": "Bundle components (JSON)", "type": "json", "description": "Required for multi_product / mix_match. Array of {product_handle, qty}." },
+      { "key": "bundle_quantity_tiers", "name": "Bundle quantity tiers (JSON)", "type": "json", "description": "Required for quantity_tiers. Array of {qty, discount_pct}. Mirrors quantity_breaks schema." },
+      { "key": "bundle_show_in_catalog", "name": "Show in main catalog", "type": "boolean", "default": true },
+      { "key": "bundle_surfaces_enabled", "name": "Surfaces enabled (JSON)", "type": "json", "description": "Per-bundle surface allowlist. Array of 1..6. Absent = all enabled at tenant level." },
+      { "key": "bundle_copy", "name": "Per-surface copy (JSON)", "type": "json", "description": "Per-surface eyebrow/heading/cta overrides." },
+      { "key": "bundle_free_gift_enabled", "name": "Free gift enabled", "type": "boolean", "default": false },
+      { "key": "bundle_free_gift_handle", "name": "Free gift product handle", "type": "single_line_text_field" },
+      { "key": "bundle_fomo_mode", "name": "FOMO mode", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"none\",\"discount\",\"scarcity\",\"both\"]" }] },
+      { "key": "bundle_fomo_cycle_days", "name": "FOMO cycle (days)", "type": "number_integer" },
+      { "key": "bundle_fomo_stock_count", "name": "FOMO stock count", "type": "number_integer" },
+      { "key": "bundle_cross_supplier", "name": "Cross-supplier", "type": "boolean", "default": false },
+      { "key": "bundle_supplier_count", "name": "Supplier count", "type": "number_integer" },
+      { "key": "bundle_savings_pct", "name": "Computed savings percent", "type": "number_decimal", "description": "Precomputed for fast banner / card render. Recomputed by runwell-shopify rebuild-bundle-index." },
+      { "key": "bundle_byob_candidates", "name": "BYOB candidates", "type": "list.product_reference", "description": "Mode C only. Pool of candidate products the customer can pick from.", "v1_5": true },
+      { "key": "bundle_byob_min_picks", "name": "BYOB min picks", "type": "number_integer", "description": "Mode C only. Minimum required selections before ATC enables.", "v1_5": true },
+      { "key": "bundle_byob_max_picks", "name": "BYOB max picks", "type": "number_integer", "description": "Mode C only. Maximum allowed selections.", "v1_5": true },
+      { "key": "bundle_byob_layout", "name": "BYOB picker layout", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"grid\",\"accordion\",\"radio\"]" }], "description": "Mode C only. Default grid.", "v1_5": true },
+      { "key": "bundle_byob_categories", "name": "BYOB categories", "type": "json", "description": "Mode C only. Optional. Array of {label, handles: [product_handle]} to group candidates.", "v1_5": true },
+      { "key": "bundle_byob_required_handles", "name": "BYOB required handles", "type": "list.product_reference", "description": "Mode C only. Pre-selected, not deselectable.", "v1_5": true },
+      { "key": "subscription_enabled", "name": "Subscription enabled (v2)", "type": "boolean", "default": false, "v2_only": true },
+      { "key": "subscription_interval", "name": "Subscription interval (JSON, v2)", "type": "json", "v2_only": true },
+      { "key": "subscription_discount_pct", "name": "Subscription discount percent (v2)", "type": "number_decimal", "v2_only": true },
+      { "key": "subscription_badge_copy", "name": "Subscription badge copy (v2)", "type": "single_line_text_field", "v2_only": true }
+    ]
+  },
+  "shop_metaobjects": [
+    {
+      "type": "bundle_index",
+      "name": "Bundle index",
+      "description": "Forward map (bundles -> components) and reverse map (products -> bundles) used by surfaces 2/4 to avoid N+1 reads. Single instance per shop. Rebuilt by runwell-shopify rebuild-bundle-index or by Shopify Flow on bundle product create/update.",
+      "field_definitions": [
+        { "key": "entries", "name": "Entries", "type": "json", "description": "{products: {handle: [bundle_handles]}, bundles: {handle: {components: {handle: qty}}}}" }
+      ]
+    }
+  ],
+  "cross_field_validation": [
+    { "rule": "bundle_quantity_tiers required when bundle_mode == 'quantity_tiers'", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_components required when bundle_mode in ['multi_product','mix_match']", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_byob_candidates + bundle_byob_min_picks + bundle_byob_max_picks required when bundle_mode == 'byob'", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_byob_min_picks <= bundle_byob_max_picks", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_byob_layout == 'radio' requires bundle_byob_categories", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_pricing_value shape matches bundle_pricing_model (see spec.md section 2.2)", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_free_gift_handle required when bundle_free_gift_enabled == true", "enforced_by": "runwell-shopify qa --bundles" }
+  ]
+}