@syntrologie/runtime-sdk 0.2.0

package/schema/canvas-config.schema.json

@@ -0,0 +1,329 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://syntropyforge.com/schemas/smart-canvas-config.json",
+  "title": "Smart Canvas Configuration",
+  "type": "object",
+  "required": ["fetchedAt", "rectangles"],
+  "properties": {
+    "fetchedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "configVersion": {
+      "type": "string"
+    },
+    "canvasTitle": {
+      "type": "string"
+    },
+    "overlayRecipeUri": {
+      "type": "string",
+      "description": "Optional URI pointing to tooltip/highlight recipe"
+    },
+    "overlayRecipe": {
+      "type": "object",
+      "description": "Inline overlay recipe (for testing)",
+      "properties": {
+        "id": { "type": "string" },
+        "version": { "type": "number" },
+        "routes": { "type": "array", "items": { "type": "string" } },
+        "steps": {
+          "type": "array",
+          "items": { "oneOf": [
+            { "$ref": "#/$defs/tooltipStep" },
+            { "$ref": "#/$defs/highlightStep" }
+          ] }
+        }
+      },
+      "required": ["id", "version", "steps"],
+      "additionalProperties": false
+    },
+    "patches": {
+      "type": "array",
+      "description": "Optional host DOM patches to apply when the canvas renders",
+      "items": {
+        "$ref": "#/$defs/patch"
+      }
+    },
+    "rectangles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "content"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "subtitle": { "type": "string" },
+          "icon": { "type": "string" },
+          "size": { "type": "string", "enum": ["half", "quarter"] },
+          "order": { "type": "number" },
+          "style": {
+            "type": "object",
+            "properties": {
+              "background": { "type": "string" },
+              "borderColor": { "type": "string" },
+              "textColor": { "type": "string" },
+              "accentColor": { "type": "string" }
+            },
+            "additionalProperties": false
+          },
+          "content": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["text", "metric", "chatbot", "embed", "custom"]
+              },
+              "headline": { "type": "string" },
+              "body": { "type": "string" },
+              "metricValue": { "type": "string" },
+              "metricUnit": { "type": "string" },
+              "embedUrl": { "type": "string" },
+              "customRendererKey": { "type": "string" },
+              "actions": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["label"],
+                  "properties": {
+                    "label": { "type": "string" },
+                    "href": { "type": "string" },
+                    "onClickId": { "type": "string" }
+                  },
+                  "additionalProperties": false
+                }
+              }
+            },
+            "additionalProperties": false
+          },
+          "experiment": {
+            "type": "object",
+            "properties": {
+              "featureKey": { "type": "string" },
+              "variationId": { "type": "number" },
+              "variationValue": {},
+              "predicate": {}
+            },
+            "additionalProperties": true
+          },
+          "analyticsKey": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "anchorSelector": {
+      "type": "object",
+      "oneOf": [
+        {
+          "required": ["by", "value"],
+          "properties": {
+            "by": { "const": "css" },
+            "value": { "type": "string" },
+            "within": { "enum": ["document", "shadow"] }
+          },
+          "additionalProperties": false
+        },
+        {
+          "required": ["by", "key"],
+          "properties": {
+            "by": { "const": "data" },
+            "key": { "type": "string" },
+            "value": { "type": "string" },
+            "within": { "enum": ["document", "shadow"] }
+          },
+          "additionalProperties": false
+        },
+        {
+          "required": ["by"],
+          "properties": {
+            "by": { "const": "aria" },
+            "role": { "type": "string" },
+            "label": { "type": "string" },
+            "within": { "enum": ["document", "shadow"] }
+          },
+          "additionalProperties": false
+        },
+        {
+          "required": ["by", "el"],
+          "properties": {
+            "by": { "const": "ref" },
+            "el": {}
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "operation": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "const": "append" },
+            "html": { "type": "string" },
+            "position": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "const": "prepend" },
+            "html": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind", "where"],
+          "properties": {
+            "kind": { "const": "insertAdjacent" },
+            "where": {
+              "enum": ["beforebegin", "afterbegin", "beforeend", "afterend"]
+            },
+            "html": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind", "className"],
+          "properties": {
+            "kind": { "enum": ["addClass", "removeClass"] },
+            "className": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind", "name"],
+          "properties": {
+            "kind": { "const": "setAttr" },
+            "name": { "type": "string" },
+            "value": { "type": ["string", "null"] }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind", "prop"],
+          "properties": {
+            "kind": { "const": "setStyle" },
+            "prop": { "type": "string" },
+            "value": { "type": ["string", "null"] },
+            "important": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind", "text"],
+          "properties": {
+            "kind": { "const": "setText" },
+            "text": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "patch": {
+      "type": "object",
+      "required": ["id", "anchor", "operations"],
+      "properties": {
+        "id": { "type": "string" },
+        "anchor": { "$ref": "#/$defs/anchorSelector" },
+        "tier": { "enum": ["additive", "moderate", "surgical"] },
+        "operations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/operation" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "tooltipStep": {
+      "type": "object",
+      "required": ["kind", "id", "anchor", "content"],
+      "properties": {
+        "kind": { "const": "tooltip" },
+        "id": { "type": "string" },
+        "anchor": { "$ref": "#/$defs/anchorSelector" },
+        "content": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string" },
+            "body": { "type": "string" }
+          },
+          "required": ["body"],
+          "additionalProperties": false
+        },
+        "placement": { "enum": ["top","bottom","left","right","auto"] },
+        "offsetPx": { "type": "number" },
+        "blocking": { "type": "boolean" },
+        "trigger": { "enum": ["immediate","hover","click"] },
+        "ctaButtons": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": { "type": "string" },
+              "actionId": { "type": "string" }
+            },
+            "required": ["label","actionId"],
+            "additionalProperties": false
+          }
+        },
+        "dismiss": {
+          "type": "object",
+          "properties": {
+            "onEsc": { "type": "boolean" },
+            "closeButton": { "type": "boolean" },
+            "timeoutMs": { "type": "number" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "highlightStep": {
+      "type": "object",
+      "required": ["kind", "id", "anchor"],
+      "properties": {
+        "kind": { "const": "highlight" },
+        "id": { "type": "string" },
+        "anchor": { "$ref": "#/$defs/anchorSelector" },
+        "copy": { "type": "string" },
+        "ring": {
+          "type": "object",
+          "properties": {
+            "paddingPx": { "type": "number" },
+            "radiusPx": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        "scrim": {
+          "type": "object",
+          "properties": {
+            "opacity": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        "ringColor": { "type": "string" },
+        "blocking": { "type": "boolean" },
+        "dismiss": {
+          "type": "object",
+          "properties": {
+            "onClickOutside": { "type": "boolean" },
+            "onEsc": { "type": "boolean" },
+            "timeoutMs": { "type": "number" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/scripts/validate-config.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const schemaPath = path.resolve(__dirname, "../schema/canvas-config.schema.json");
+
+const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
+
+const usage = () => {
+  console.error("Usage: npm run validate-config -- <path/to/config.json>");
+};
+
+const targetPath = process.argv[2];
+if (!targetPath) {
+  usage();
+  process.exit(1);
+}
+
+const configPath = path.resolve(process.cwd(), targetPath);
+
+const loadJson = (file) => JSON.parse(fs.readFileSync(file, "utf-8"));
+
+const errors = [];
+
+const validateSchema = (schemaNode, value, pointer = "$") => {
+  if (schemaNode.type) {
+    const types = Array.isArray(schemaNode.type) ? schemaNode.type : [schemaNode.type];
+    const matches = types.some((t) => typeof value === t || (t === "array" && Array.isArray(value)) || (t === "object" && value && typeof value === "object" && !Array.isArray(value)));
+    if (!matches) {
+      errors.push(`${pointer}: expected ${schemaNode.type}, received ${Array.isArray(value) ? "array" : typeof value}`);
+      return;
+    }
+  }
+
+  if (schemaNode.enum && !schemaNode.enum.includes(value)) {
+    errors.push(`${pointer}: value must be one of ${schemaNode.enum.join(", ")}`);
+  }
+
+  if (schemaNode.required && typeof value === "object" && !Array.isArray(value)) {
+    for (const key of schemaNode.required) {
+      if (!(key in value)) {
+        errors.push(`${pointer}: missing required property "${key}"`);
+      }
+    }
+  }
+
+  if (schemaNode.properties && typeof value === "object" && value) {
+    for (const [key, subSchema] of Object.entries(schemaNode.properties)) {
+      if (key in value) {
+        validateSchema(subSchema, value[key], `${pointer}.${key}`);
+      }
+    }
+  }
+
+  if (schemaNode.items && Array.isArray(value)) {
+    value.forEach((item, idx) => validateSchema(schemaNode.items, item, `${pointer}[${idx}]`));
+  }
+};
+
+let data;
+try {
+  data = loadJson(configPath);
+} catch (err) {
+  console.error(`Failed to read ${configPath}:`, err.message);
+  process.exit(1);
+}
+
+validateSchema(schema, data);
+
+if (errors.length) {
+  console.error(`❌ Config invalid (${errors.length} issues):`);
+  for (const err of errors) {
+    console.error(`  - ${err}`);
+  }
+  process.exit(1);
+}
+
+console.log(`✅ ${path.relative(process.cwd(), configPath)} is valid.`);