@colixsystems/widget-sdk 0.2.0 → 0.4.1

package/dist/manifest.cjs

@@ -0,0 +1,144 @@
+// CommonJS mirror of manifest.js. Lets backend services (CJS) call
+// `validateManifest(...)` without a dynamic-import detour. The two files
+// share their constants by mutual import via createRequire — manifest.js
+// re-exports the same functions defined here so there is exactly one
+// implementation.
+
+const VALID_CATEGORIES = new Set([
+  "input", "display", "layout", "data", "media", "communication", "custom",
+  "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM",
+]);
+const VALID_PLATFORMS = new Set(["web", "native"]);
+
+function canonicalCategory(c) {
+  if (typeof c !== "string") return null;
+  const upper = c.toUpperCase();
+  return [
+    "INPUT",
+    "DISPLAY",
+    "LAYOUT",
+    "DATA",
+    "MEDIA",
+    "COMMUNICATION",
+    "CUSTOM",
+  ].includes(upper)
+    ? upper
+    : null;
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SEMVER_RANGE_RE = /^[\^~>=<]*\s*\d+\.\d+\.\d+/;
+const ID_RE = /^[a-z0-9]+(?:\.[a-z0-9-]+)+$/;
+
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.length > 0;
+}
+
+function pushIf(errors, cond, msg) {
+  if (!cond) errors.push(msg);
+}
+
+function validateManifest(m) {
+  const errors = [];
+  if (m === null || typeof m !== "object") {
+    return { ok: false, errors: ["manifest must be an object"] };
+  }
+  const manifest = m;
+
+  pushIf(errors, isNonEmptyString(manifest.id), "manifest.id must be a non-empty string");
+  if (isNonEmptyString(manifest.id)) {
+    pushIf(
+      errors,
+      ID_RE.test(manifest.id),
+      "manifest.id must be reverse-DNS, e.g. com.acme.charts.barchart",
+    );
+  }
+
+  pushIf(errors, isNonEmptyString(manifest.name), "manifest.name must be a non-empty string");
+
+  pushIf(errors, isNonEmptyString(manifest.version), "manifest.version must be a non-empty string");
+  if (isNonEmptyString(manifest.version)) {
+    pushIf(errors, SEMVER_RE.test(manifest.version), "manifest.version must be a valid semver");
+  }
+
+  pushIf(
+    errors,
+    typeof manifest.category === "string" && VALID_CATEGORIES.has(manifest.category),
+    `manifest.category must be one of ${[...VALID_CATEGORIES].join(", ")}`,
+  );
+
+  pushIf(errors, isNonEmptyString(manifest.icon), "manifest.icon must be a non-empty string");
+  pushIf(errors, isNonEmptyString(manifest.description), "manifest.description must be a non-empty string");
+
+  if (manifest.author === null || typeof manifest.author !== "object") {
+    errors.push("manifest.author must be an object with a name");
+  } else {
+    const author = manifest.author;
+    pushIf(errors, isNonEmptyString(author.name), "manifest.author.name must be a non-empty string");
+    if (author.url !== undefined) {
+      pushIf(errors, isNonEmptyString(author.url), "manifest.author.url must be a string");
+    }
+    if (author.email !== undefined) {
+      pushIf(errors, isNonEmptyString(author.email), "manifest.author.email must be a string");
+    }
+  }
+
+  if (!Array.isArray(manifest.supportedPlatforms) || manifest.supportedPlatforms.length === 0) {
+    errors.push("manifest.supportedPlatforms must be a non-empty array");
+  } else {
+    for (const p of manifest.supportedPlatforms) {
+      if (!VALID_PLATFORMS.has(p)) {
+        errors.push(`manifest.supportedPlatforms contains invalid value "${p}"`);
+      }
+    }
+  }
+
+  pushIf(
+    errors,
+    isNonEmptyString(manifest.minAppStudioVersion),
+    "manifest.minAppStudioVersion must be a non-empty string",
+  );
+  if (isNonEmptyString(manifest.minAppStudioVersion)) {
+    pushIf(
+      errors,
+      SEMVER_RANGE_RE.test(manifest.minAppStudioVersion),
+      "manifest.minAppStudioVersion must be a semver range, e.g. >=2.4.0",
+    );
+  }
+
+  if (!Array.isArray(manifest.requestedScopes)) {
+    errors.push("manifest.requestedScopes must be an array (use [] for none)");
+  } else {
+    for (const s of manifest.requestedScopes) {
+      if (!isNonEmptyString(s)) {
+        errors.push("manifest.requestedScopes entries must be non-empty strings");
+        break;
+      }
+    }
+  }
+
+  if (manifest.propertySchema === null || typeof manifest.propertySchema !== "object") {
+    errors.push("manifest.propertySchema must be an object");
+  }
+
+  if (!Array.isArray(manifest.events)) {
+    errors.push("manifest.events must be an array (use [] for none)");
+  } else {
+    for (const e of manifest.events) {
+      if (e === null || typeof e !== "object") {
+        errors.push("manifest.events entries must be objects");
+        break;
+      }
+      if (!isNonEmptyString(e.name)) {
+        errors.push("manifest.events[].name must be a non-empty string");
+      }
+    }
+  }
+
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+module.exports = {
+  validateManifest,
+  canonicalCategory,
+};

package/dist/manifest.js

@@ -1,133 +1,15 @@
 // Shape validation for WidgetManifest per docs/architecture/widget-marketplace.md §2.1.
 // Pure JS — no third-party deps. Banned-identifier scanning lives in linter.js.
+//
+// The implementation lives in `manifest.cjs` so backend services (CJS
+// runtime) can `require` the same validator the SDK ships to ESM
+// consumers. This file is a thin re-export so ESM imports keep working
+// unchanged.
 
-// REQ-MKT canonical category values are uppercase (matching the Prisma
-// `WidgetCategory` enum used to persist them server-side). We accept both
-// cases on input — lowercase is the form spelled out in design doc §2.2
-// and the TS types — and canonicalize internally via `canonicalCategory`.
-const VALID_CATEGORIES = new Set([
-  "input", "display", "layout", "data", "media", "communication", "custom",
-  "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM",
-]);
-const VALID_PLATFORMS = new Set(["web", "native"]);
+import { createRequire } from "module";
 
-/**
- * Normalize a manifest category to its canonical (uppercase) form.
- * Returns `null` if the input is not a recognised category.
- * @param {unknown} c
- * @returns {string | null}
- */
-export function canonicalCategory(c) {
-  if (typeof c !== "string") return null;
-  const upper = c.toUpperCase();
-  return ["INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM"].includes(upper) ? upper : null;
-}
-const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
-const SEMVER_RANGE_RE = /^[\^~>=<]*\s*\d+\.\d+\.\d+/;
-const ID_RE = /^[a-z0-9]+(?:\.[a-z0-9-]+)+$/;
+const require = createRequire(import.meta.url);
+const cjs = require("./manifest.cjs");
 
-function isNonEmptyString(v) {
-  return typeof v === "string" && v.length > 0;
-}
-
-function pushIf(errors, cond, msg) {
-  if (!cond) errors.push(msg);
-}
-
-/**
- * Validates a WidgetManifest shape.
- * @param {unknown} m
- * @returns {{ ok: true } | { ok: false, errors: string[] }}
- */
-export function validateManifest(m) {
-  const errors = [];
-
-  if (m === null || typeof m !== "object") {
-    return { ok: false, errors: ["manifest must be an object"] };
-  }
-
-  const manifest = /** @type {Record<string, unknown>} */ (m);
-
-  pushIf(errors, isNonEmptyString(manifest.id), "manifest.id must be a non-empty string");
-  if (isNonEmptyString(manifest.id)) {
-    pushIf(errors, ID_RE.test(/** @type {string} */ (manifest.id)),
-      "manifest.id must be reverse-DNS, e.g. com.acme.charts.barchart");
-  }
-
-  pushIf(errors, isNonEmptyString(manifest.name), "manifest.name must be a non-empty string");
-
-  pushIf(errors, isNonEmptyString(manifest.version), "manifest.version must be a non-empty string");
-  if (isNonEmptyString(manifest.version)) {
-    pushIf(errors, SEMVER_RE.test(/** @type {string} */ (manifest.version)),
-      "manifest.version must be a valid semver");
-  }
-
-  pushIf(errors,
-    typeof manifest.category === "string" && VALID_CATEGORIES.has(manifest.category),
-    `manifest.category must be one of ${[...VALID_CATEGORIES].join(", ")}`);
-
-  pushIf(errors, isNonEmptyString(manifest.icon), "manifest.icon must be a non-empty string");
-  pushIf(errors, isNonEmptyString(manifest.description), "manifest.description must be a non-empty string");
-
-  if (manifest.author === null || typeof manifest.author !== "object") {
-    errors.push("manifest.author must be an object with a name");
-  } else {
-    const author = /** @type {Record<string, unknown>} */ (manifest.author);
-    pushIf(errors, isNonEmptyString(author.name), "manifest.author.name must be a non-empty string");
-    if (author.url !== undefined) {
-      pushIf(errors, isNonEmptyString(author.url), "manifest.author.url must be a string");
-    }
-    if (author.email !== undefined) {
-      pushIf(errors, isNonEmptyString(author.email), "manifest.author.email must be a string");
-    }
-  }
-
-  if (!Array.isArray(manifest.supportedPlatforms) || manifest.supportedPlatforms.length === 0) {
-    errors.push("manifest.supportedPlatforms must be a non-empty array");
-  } else {
-    for (const p of manifest.supportedPlatforms) {
-      if (!VALID_PLATFORMS.has(p)) {
-        errors.push(`manifest.supportedPlatforms contains invalid value "${p}"`);
-      }
-    }
-  }
-
-  pushIf(errors, isNonEmptyString(manifest.minAppStudioVersion),
-    "manifest.minAppStudioVersion must be a non-empty string");
-  if (isNonEmptyString(manifest.minAppStudioVersion)) {
-    pushIf(errors, SEMVER_RANGE_RE.test(/** @type {string} */ (manifest.minAppStudioVersion)),
-      "manifest.minAppStudioVersion must be a semver range, e.g. >=2.4.0");
-  }
-
-  if (!Array.isArray(manifest.requestedScopes)) {
-    errors.push("manifest.requestedScopes must be an array (use [] for none)");
-  } else {
-    for (const s of manifest.requestedScopes) {
-      if (!isNonEmptyString(s)) {
-        errors.push("manifest.requestedScopes entries must be non-empty strings");
-        break;
-      }
-    }
-  }
-
-  if (manifest.propertySchema === null || typeof manifest.propertySchema !== "object") {
-    errors.push("manifest.propertySchema must be an object");
-  }
-
-  if (!Array.isArray(manifest.events)) {
-    errors.push("manifest.events must be an array (use [] for none)");
-  } else {
-    for (const e of manifest.events) {
-      if (e === null || typeof e !== "object") {
-        errors.push("manifest.events entries must be objects");
-        break;
-      }
-      const ev = /** @type {Record<string, unknown>} */ (e);
-      if (!isNonEmptyString(ev.name)) {
-        errors.push("manifest.events[].name must be a non-empty string");
-      }
-    }
-  }
-
-  return errors.length === 0 ? { ok: true } : { ok: false, errors };
-}
+export const validateManifest = cjs.validateManifest;
+export const canonicalCategory = cjs.canonicalCategory;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,6 +17,12 @@
     "./linter": {
       "import": "./dist/linter.js",
       "default": "./dist/linter.js"
+    },
+    "./contract": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/contract.cjs",
+      "import": "./dist/contract.js",
+      "default": "./dist/contract.cjs"
     }
   },
   "bin": {
@@ -29,7 +35,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src"
+    "test": "node --test src/__tests__/contract.test.js"
   },
   "engines": {
     "node": ">=18"