@colixsystems/widget-sdk 0.18.0 → 0.19.0

package/dist/manifest.cjs

@@ -5,11 +5,78 @@
 // implementation.
 
 const VALID_CATEGORIES = new Set([
-  "input", "display", "layout", "data", "media", "communication", "custom",
-  "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM",
+  "input", "display", "layout", "data", "media", "communication", "administration", "custom",
+  "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "ADMINISTRATION", "CUSTOM",
 ]);
 const VALID_PLATFORMS = new Set(["web", "native"]);
 
+// REQ-WIDGET-ACTION — structural validation for manifest-declared server
+// actions. Mirrors the backend action.service caps; the runner re-validates
+// the cron expression (node-cron) and binds the tenant-local API key + table
+// at enable time, so we only check shape + size here (cross-env: no Buffer).
+const VALID_ACTION_TRIGGERS = new Set([
+  "schedule",
+  "record_created",
+  "record_updated",
+  "record_deleted",
+]);
+const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
+const ACTION_TIMEOUT_MIN_MS = 100;
+const ACTION_TIMEOUT_MAX_MS = 5 * 60 * 1000;
+
+function utf8ByteLength(s) {
+  return new TextEncoder().encode(s).length;
+}
+
+function validateManifestActions(actions, errors) {
+  if (!Array.isArray(actions)) {
+    errors.push("manifest.actions must be an array (omit it or use [] for none)");
+    return;
+  }
+  const seenKeys = new Set();
+  for (const a of actions) {
+    if (a === null || typeof a !== "object") {
+      errors.push("manifest.actions entries must be objects");
+      break;
+    }
+    if (!isNonEmptyString(a.key)) {
+      errors.push("manifest.actions[].key must be a non-empty string");
+    } else if (seenKeys.has(a.key)) {
+      errors.push(`manifest.actions[].key "${a.key}" is duplicated`);
+    } else {
+      seenKeys.add(a.key);
+    }
+    pushIf(errors, isNonEmptyString(a.name), "manifest.actions[].name must be a non-empty string");
+    if (!VALID_ACTION_TRIGGERS.has(a.triggerType)) {
+      errors.push(
+        `manifest.actions[].triggerType must be one of ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
+      );
+    } else if (a.triggerType === "schedule") {
+      pushIf(
+        errors,
+        isNonEmptyString(a.scheduleCron),
+        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+      );
+    }
+    if (!isNonEmptyString(a.scriptSource)) {
+      errors.push("manifest.actions[].scriptSource must be a non-empty string");
+    } else if (utf8ByteLength(a.scriptSource) > ACTION_SCRIPT_MAX_BYTES) {
+      errors.push("manifest.actions[].scriptSource exceeds 200 KiB");
+    }
+    if (a.timeoutMs !== undefined) {
+      const t = Number(a.timeoutMs);
+      if (!Number.isFinite(t) || t < ACTION_TIMEOUT_MIN_MS || t > ACTION_TIMEOUT_MAX_MS) {
+        errors.push("manifest.actions[].timeoutMs must be between 100 and 300000");
+      }
+    }
+    if (a.triggerTableId !== undefined || a.apiKeyId !== undefined) {
+      errors.push(
+        "manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install",
+      );
+    }
+  }
+}
+
 function canonicalCategory(c) {
   if (typeof c !== "string") return null;
   const upper = c.toUpperCase();
@@ -20,6 +87,7 @@ function canonicalCategory(c) {
     "DATA",
     "MEDIA",
     "COMMUNICATION",
+    "ADMINISTRATION",
     "CUSTOM",
   ].includes(upper)
     ? upper
@@ -135,6 +203,11 @@ function validateManifest(m) {
     }
   }
 
+  // `actions` is optional (additive in SDK 1.8.0) — only validate when present.
+  if (manifest.actions !== undefined) {
+    validateManifestActions(manifest.actions, errors);
+  }
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 

package/dist/manifest.js

@@ -5,11 +5,78 @@
 // implementation.
 
 const VALID_CATEGORIES = new Set([
-  "input", "display", "layout", "data", "media", "communication", "custom",
-  "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM",
+  "input", "display", "layout", "data", "media", "communication", "administration", "custom",
+  "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "ADMINISTRATION", "CUSTOM",
 ]);
 const VALID_PLATFORMS = new Set(["web", "native"]);
 
+// REQ-WIDGET-ACTION — structural validation for manifest-declared server
+// actions. Mirrors the backend action.service caps; the runner re-validates
+// the cron expression (node-cron) and binds the tenant-local API key + table
+// at enable time, so we only check shape + size here (cross-env: no Buffer).
+const VALID_ACTION_TRIGGERS = new Set([
+  "schedule",
+  "record_created",
+  "record_updated",
+  "record_deleted",
+]);
+const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
+const ACTION_TIMEOUT_MIN_MS = 100;
+const ACTION_TIMEOUT_MAX_MS = 5 * 60 * 1000;
+
+function utf8ByteLength(s) {
+  return new TextEncoder().encode(s).length;
+}
+
+function validateManifestActions(actions, errors) {
+  if (!Array.isArray(actions)) {
+    errors.push("manifest.actions must be an array (omit it or use [] for none)");
+    return;
+  }
+  const seenKeys = new Set();
+  for (const a of actions) {
+    if (a === null || typeof a !== "object") {
+      errors.push("manifest.actions entries must be objects");
+      break;
+    }
+    if (!isNonEmptyString(a.key)) {
+      errors.push("manifest.actions[].key must be a non-empty string");
+    } else if (seenKeys.has(a.key)) {
+      errors.push(`manifest.actions[].key "${a.key}" is duplicated`);
+    } else {
+      seenKeys.add(a.key);
+    }
+    pushIf(errors, isNonEmptyString(a.name), "manifest.actions[].name must be a non-empty string");
+    if (!VALID_ACTION_TRIGGERS.has(a.triggerType)) {
+      errors.push(
+        `manifest.actions[].triggerType must be one of ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
+      );
+    } else if (a.triggerType === "schedule") {
+      pushIf(
+        errors,
+        isNonEmptyString(a.scheduleCron),
+        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+      );
+    }
+    if (!isNonEmptyString(a.scriptSource)) {
+      errors.push("manifest.actions[].scriptSource must be a non-empty string");
+    } else if (utf8ByteLength(a.scriptSource) > ACTION_SCRIPT_MAX_BYTES) {
+      errors.push("manifest.actions[].scriptSource exceeds 200 KiB");
+    }
+    if (a.timeoutMs !== undefined) {
+      const t = Number(a.timeoutMs);
+      if (!Number.isFinite(t) || t < ACTION_TIMEOUT_MIN_MS || t > ACTION_TIMEOUT_MAX_MS) {
+        errors.push("manifest.actions[].timeoutMs must be between 100 and 300000");
+      }
+    }
+    if (a.triggerTableId !== undefined || a.apiKeyId !== undefined) {
+      errors.push(
+        "manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install",
+      );
+    }
+  }
+}
+
 function canonicalCategory(c) {
   if (typeof c !== "string") return null;
   const upper = c.toUpperCase();
@@ -20,6 +87,7 @@ function canonicalCategory(c) {
     "DATA",
     "MEDIA",
     "COMMUNICATION",
+    "ADMINISTRATION",
     "CUSTOM",
   ].includes(upper)
     ? upper
@@ -135,6 +203,11 @@ function validateManifest(m) {
     }
   }
 
+  // `actions` is optional (additive in SDK 1.8.0) — only validate when present.
+  if (manifest.actions !== undefined) {
+    validateManifestActions(manifest.actions, errors);
+  }
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/linter-users-scope.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js"
   },
   "engines": {
     "node": ">=18"