@nextcommerce/campaigns-os 1.33.0

package/schemas/campaign-runtime-build-packet.v0.schema.json

@@ -0,0 +1,452 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaign-runtime-build-packet.v0.schema.json",
+  "title": "Campaigns OS Build Packet v0",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "campaign", "spec", "source_html", "assembly", "deploy", "qa"],
+  "properties": {
+    "schema_version": {
+      "const": "campaign-runtime-build-packet/v0"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "UTC instant this packet was generated by prepare-build, ISO-8601 with a Z suffix. Optional for packets generated before it existed; always stamped on new packets. Downstream freshness (campaigns-agent readback staleness and multi-packet selection) reads this field, never file mtime."
+    },
+    "campaign": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["public_route_slug", "allowed_domains_confirmed"],
+      "properties": {
+        "public_route_slug": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Shopper-facing route slug, e.g. theduo-v3. It is often the same as the campaign directory, but the packet keeps them explicit. Always required as campaign identity, even for root-served campaigns (see route_root)."
+        },
+        "route_root": {
+          "type": ["string", "null"],
+          "pattern": "^/(?:[A-Za-z0-9._-]+/)?$",
+          "description": "Public route root the campaign is served under. \"/\" declares a root-served campaign: pages live at site-root paths (/checkout-v2, /receipt) with no slug prefix, so routing metas and public routes are validated against the site root. Defaults to \"/<public_route_slug>/\" when absent; when present and not \"/\", it must equal \"/<public_route_slug>/\". Built output still lives at _site/<public_route_slug>/ either way — route_root describes the SERVED path shape, not the build directory."
+        },
+        "campaign_directory": {
+          "type": ["string", "null"],
+          "description": "Directory name inside the target repo for assembled campaign files, e.g. theduo-v3."
+        },
+        "live_url_path": {
+          "type": ["string", "null"],
+          "description": "Expected deployed path for this campaign, e.g. /theduo-v3/."
+        },
+        "campaigns_app_url": {
+          "type": ["string", "null"]
+        },
+        "api_key_source": {
+          "type": "string",
+          "description": "Optional fallback source, usually env:<VAR>, when the local CampaignSpec does not carry campaign.campaigns_api_key."
+        },
+        "api_key": {
+          "type": ["string", "null"],
+          "description": "Legacy direct/local value. Prefer campaigns_api_key or the local CampaignSpec campaign.campaigns_api_key."
+        },
+        "campaigns_api_key": {
+          "type": ["string", "null"],
+          "description": "Direct/local Campaigns API key. Campaigns API keys are public-facing and domain-allowlisted; shared examples may still prefer spec or env sourcing."
+        },
+        "allowed_domains_confirmed": {
+          "type": "boolean"
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["map_id"],
+      "properties": {
+        "map_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Saved Map Builder identity used for reopen, /api/spec/<map-id>, QA verdicts, and provenance."
+        },
+        "spec_url": {
+          "type": ["string", "null"]
+        },
+        "local_path": {
+          "type": ["string", "null"]
+        }
+      },
+      "anyOf": [
+        { "required": ["spec_url"] },
+        { "required": ["local_path"] }
+      ]
+    },
+    "design_source_package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "schema_version", "sha256", "material_fingerprint"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "schema_version": { "const": "campaign-design-source-package/v0" },
+        "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "material_fingerprint": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      },
+      "description": "Packet-relative reference to the normalized Design Source Package. sha256 hashes the exact artifact bytes; material_fingerprint drives freshness gates."
+    },
+    "source_html": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["root", "pages"],
+      "properties": {
+        "root": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pages": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["page_id"],
+            "properties": {
+              "page_id": { "type": "string", "minLength": 1 },
+              "path": { "type": "string", "minLength": 1 },
+              "page_type": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Producer or CampaignSpec page type. This may use richer authoring vocabulary than the Page Kit runtime projection in page_kit.page_type."
+              },
+              "upsell_template_pattern": { "type": "string", "minLength": 1 },
+              "upsell_mv_tiers": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["min", "max"],
+                "properties": {
+                  "min": { "type": "integer", "minimum": 1 },
+                  "max": { "type": "integer", "minimum": 1 }
+                }
+              },
+              "variant_labels": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["primary"],
+                "properties": {
+                  "primary": { "type": "string", "minLength": 1 },
+                  "secondary": { "type": "string", "minLength": 1 }
+                }
+              },
+              "source_hash": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$",
+                "description": "Optional sha256 of the source HTML file at the time the manifest was written. Doctor compares this to the on-disk file's actual hash and warns on mismatch (Slice 6 drift detection)."
+              },
+              "page_kit": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["target_path", "output_path", "public_route", "spec_route", "page_type", "permalink_required", "frontmatter"],
+                "properties": {
+                  "target_path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Target page file relative to assembly.output_dir. This is the Page Kit target shape; it is distinct from source_html.pages[].path, which remains producer/source provenance."
+                  },
+                  "output_path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Target page file relative to assembly.target_repo."
+                  },
+                  "public_route": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Rendered campaign-rooted public route Page Kit should produce for this page."
+                  },
+                  "spec_route": {
+                    "type": "string",
+                    "description": "CampaignSpec route after removing the public campaign slug, when present."
+                  },
+                  "page_type": {
+                    "enum": ["product", "checkout", "upsell", "receipt"],
+                    "description": "Page Kit runtime/analytics page_type. Preserve richer CampaignSpec or producer page types in source metadata instead."
+                  },
+                  "permalink_required": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "True when Page Kit's default filename route would not match public_route and frontmatter.permalink should be written."
+                  },
+                  "frontmatter": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["page_type"],
+                    "properties": {
+                      "page_type": {
+                        "enum": ["product", "checkout", "upsell", "receipt"],
+                        "description": "Page Kit runtime/analytics page_type. This is authoritative for generated frontmatter and may differ from source_html.pages[].page_type."
+                      },
+                      "permalink": { "type": "string", "minLength": 1 },
+                      "next_url": { "type": "string", "minLength": 1 },
+                      "decline_url": { "type": "string", "minLength": 1 }
+                    }
+                  }
+                },
+                "allOf": [
+                  {
+                    "if": {
+                      "properties": { "permalink_required": { "const": true } },
+                      "required": ["permalink_required"]
+                    },
+                    "then": {
+                      "properties": {
+                        "frontmatter": {
+                          "required": ["permalink"]
+                        }
+                      }
+                    }
+                  }
+                ]
+              },
+              "skip_reason": { "type": "string", "minLength": 1 },
+              "notes": { "type": ["string", "null"] }
+            },
+            "anyOf": [
+              { "required": ["path"] },
+              { "required": ["skip_reason"] }
+            ]
+          }
+        },
+        "adapter_contract": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": [
+            "raw_html_conversion_status",
+            "source_asset_strategy",
+            "commerce_shell_adoption",
+            "route_rewrite_policy",
+            "template_files_copied",
+            "config_script_strategy",
+            "wrapper_policy",
+            "frontmatter_policy",
+            "script_style_reference_policy",
+            "cta_rewrite_policy",
+            "layout_choice"
+          ],
+          "properties": {
+            "raw_html_conversion_status": { "enum": ["pending", "in_progress", "completed", "not_required", "blocked"] },
+            "source_asset_strategy": { "enum": ["pagekit_campaign_asset_root", "external_cdn", "raw_passthrough", "not_applicable", "unknown"] },
+            "commerce_shell_adoption": { "enum": ["not_required", "template_clone_first_required", "template_clone_first_verified", "sdk_surfaces_preserved", "custom_html_experimental"] },
+            "route_rewrite_policy": { "enum": ["campaignspec_routes_via_campaign_link", "pagekit_public_routes", "raw_passthrough", "not_applicable", "unknown"] },
+            "config_script_strategy": { "enum": ["campaign_asset", "frontmatter_script", "inline", "not_required", "unknown"] },
+            "wrapper_policy": { "enum": ["strip_document_wrappers", "preserve_document_wrappers", "not_required", "unknown"] },
+            "frontmatter_policy": { "enum": ["pagekit_yaml_frontmatter", "raw_passthrough", "not_required", "unknown"] },
+            "script_style_reference_policy": { "enum": ["frontmatter_or_campaign_asset", "frontmatter", "campaign_asset", "inline", "raw_passthrough", "not_required", "unknown"] },
+            "cta_rewrite_policy": { "enum": ["campaignspec_routes_via_campaign_link", "pagekit_public_routes", "raw_passthrough", "not_applicable", "unknown"] },
+            "layout_choice": { "enum": ["campaign_layout", "page_layout", "raw_passthrough", "not_applicable", "unknown"] },
+            "template_files_copied": {
+              "type": "object",
+              "additionalProperties": true,
+              "required": ["status", "required_groups", "groups", "paths"],
+              "properties": {
+                "status": { "enum": ["pending", "complete", "verified_existing_slice", "partial", "not_applicable"] },
+                "required_groups": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                },
+                "groups": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                },
+                "paths": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              }
+            }
+          },
+          "description": "Prepared HTML -> page-kit conversion contract scoped to source_html because it describes how producer/source HTML must be converted. Build Context and Assembly Report mirror this as adapter_decisions and should move pending values to completed/verified once wrapper stripping, frontmatter, asset moves, CTA/routes, commerce shell, and template dependency copying are settled."
+        }
+      }
+    },
+    "build_brief": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["schema_version", "mode", "status", "normalized_path", "question_count", "gate_count"],
+      "properties": {
+        "schema_version": { "const": "campaigns-os-build-brief/v1" },
+        "mode": { "enum": ["prepared", "guided_draft"] },
+        "status": { "enum": ["complete", "needs_answers", "invalid"] },
+        "input_path": { "type": ["string", "null"] },
+        "normalized_path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Packet-relative path to .campaign-runtime/input/campaign-build-brief.normalized.json."
+        },
+        "question_count": { "type": "integer", "minimum": 0 },
+        "gate_count": { "type": "integer", "minimum": 0 }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "status": { "const": "needs_answers" } },
+            "required": ["status"]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "properties": {
+                  "question_count": { "type": "integer", "minimum": 1 }
+                }
+              },
+              {
+                "properties": {
+                  "gate_count": { "type": "integer", "minimum": 1 }
+                }
+              }
+            ]
+          }
+        }
+      ],
+      "description": "Durable Campaign Build Brief reference. CampaignSpec remains operational truth; this brief is merchandising/design presentation truth."
+    },
+    "assembly": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["implementation", "target_repo", "output_dir", "template_family"],
+      "properties": {
+        "implementation": {
+          "type": "string",
+          "minLength": 1,
+          "default": "next-campaigns-build"
+        },
+        "target_repo": {
+          "type": "string",
+          "minLength": 1
+        },
+        "output_dir": {
+          "type": "string",
+          "minLength": 1
+        },
+        "template_family": {
+          "enum": [
+            "undecided",
+            "olympus",
+            "limos",
+            "demeter",
+            "olympus-mv-single-step",
+            "olympus-mv-two-step",
+            "shop-single-step",
+            "shop-three-step",
+            "custom"
+          ]
+        },
+        "template_decision_notes": {
+          "type": ["string", "null"]
+        },
+        "template_lock": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["locked"],
+          "properties": {
+            "locked": {
+              "type": "boolean",
+              "description": "True only after an explicit operator/spec-confirmed template-family decision. A confidence score alone is not enough to lock commerce surfaces."
+            },
+            "locked_by": {
+              "type": ["string", "null"],
+              "description": "Who or what locked the family, e.g. operator_flag, operator_ack, spec_hint_ack."
+            },
+            "confidence": {
+              "enum": ["none", "low", "medium", "high"]
+            },
+            "evidence": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "template_certification": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["certified"],
+              "properties": {
+                "certified": { "type": "boolean" },
+                "waiver": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["reason", "waived_by", "waived_at"],
+                  "properties": {
+                    "reason": { "type": "string", "minLength": 1 },
+                    "waived_by": { "type": "string", "minLength": 1 },
+                    "waived_at": { "type": "string", "minLength": 1 }
+                  }
+                }
+              }
+            }
+          ]
+        },
+        "commerce_catalog": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["required"],
+          "properties": {
+            "required": { "type": "boolean" },
+            "family": { "type": ["string", "null"] },
+            "version": { "type": ["string", "null"] },
+            "path": { "type": ["string", "null"] }
+          },
+          "description": "Catalog gate for template-family checkout/payment/bundle/upsell/receipt surfaces."
+        },
+        "compatible_outputs": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "deploy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["target"],
+      "properties": {
+        "target": {
+          "enum": ["netlify", "cloudflare-pages", "vercel", "shopify-proxy", "agency-ci", "local-serve", "unknown"],
+          "description": "Where the built _site/ output is served for QA. local-serve is the localhost QA path: the built output is served locally (a Development domain on any port, SDK allowed, analytics suppressed) and deploy.preview_url records that localhost origin."
+        },
+        "preview_url": {
+          "type": ["string", "null"]
+        },
+        "production_url": {
+          "type": ["string", "null"]
+        },
+        "live_url_path": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "qa": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "proof_policy": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["browser_qa_required", "typed_card_depth", "localhost_development_domain_allowed", "non_localhost_origin_allowlist_required", "order_path_depth", "operator_approval_state"],
+          "properties": {
+            "browser_qa_required": { "type": "boolean" },
+            "typed_card_depth": { "type": "string", "minLength": 1 },
+            "localhost_development_domain_allowed": { "type": "boolean" },
+            "non_localhost_origin_allowlist_required": { "type": "boolean" },
+            "order_path_depth": { "type": "string", "minLength": 1 },
+            "operator_approval_state": { "type": "string", "minLength": 1 },
+            "qa_portal_publish_default": { "type": "boolean" }
+          }
+        },
+        "test_order_policy_notes": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "notes": {
+      "type": ["string", "null"]
+    }
+  }
+}