@colixsystems/widget-sdk 0.18.0 → 0.21.1

package/dist/manifest.cjs

@@ -5,11 +5,154 @@
 // 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;
+
+// REQ-L10N-WIDGET — caps + patterns for manifest-declared translations.
+// The relative key pattern is deliberately tighter than the dictionary's
+// own KEY_RE: once the host namespaces it (`widget.<id>.<key>`) the result
+// must still satisfy the dictionary cap (128 chars / KEY_RE in
+// backend/src/core/services/l10n.service.js). The locale pattern mirrors that
+// service's LANG_CODE_RE so a manifest can't declare a locale the dictionary
+// would reject.
+const TRANSLATIONS_MAX_KEYS = 100;
+const TRANSLATION_VALUE_MAX_BYTES = 1024;
+const TRANSLATION_KEY_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+const TRANSLATION_LOCALE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;
+const TRANSLATION_FULL_KEY_MAX = 128;
+
+function utf8ByteLength(s) {
+  return new TextEncoder().encode(s).length;
+}
+
+function validateManifestTranslations(translations, manifestId, errors) {
+  if (
+    translations === null ||
+    typeof translations !== "object" ||
+    Array.isArray(translations)
+  ) {
+    errors.push(
+      "manifest.translations must be an object mapping key -> { en, <locale>? }",
+    );
+    return;
+  }
+  const keys = Object.keys(translations);
+  if (keys.length > TRANSLATIONS_MAX_KEYS) {
+    errors.push(
+      `manifest.translations may declare at most ${TRANSLATIONS_MAX_KEYS} keys`,
+    );
+  }
+  for (const key of keys) {
+    if (!TRANSLATION_KEY_RE.test(key)) {
+      errors.push(
+        `manifest.translations key "${key}" must match /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/`,
+      );
+      continue;
+    }
+    if (isNonEmptyString(manifestId)) {
+      const fullKey = `widget.${manifestId}.${key}`;
+      if (fullKey.length > TRANSLATION_FULL_KEY_MAX) {
+        errors.push(
+          `manifest.translations key "${key}" is too long once namespaced (${fullKey.length} > ${TRANSLATION_FULL_KEY_MAX} chars)`,
+        );
+      }
+    }
+    const entry = translations[key];
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      errors.push(
+        `manifest.translations["${key}"] must be an object of locale -> string`,
+      );
+      continue;
+    }
+    if (!isNonEmptyString(entry.en)) {
+      errors.push(
+        `manifest.translations["${key}"].en is required and must be a non-empty string`,
+      );
+    }
+    for (const [locale, value] of Object.entries(entry)) {
+      if (!TRANSLATION_LOCALE_RE.test(locale)) {
+        errors.push(
+          `manifest.translations["${key}"] has invalid locale "${locale}"`,
+        );
+      }
+      if (typeof value !== "string") {
+        errors.push(
+          `manifest.translations["${key}"]["${locale}"] must be a string`,
+        );
+      } else if (utf8ByteLength(value) > TRANSLATION_VALUE_MAX_BYTES) {
+        errors.push(
+          `manifest.translations["${key}"]["${locale}"] exceeds 1 KB`,
+        );
+      }
+    }
+  }
+}
+
+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 +163,7 @@ function canonicalCategory(c) {
     "DATA",
     "MEDIA",
     "COMMUNICATION",
+    "ADMINISTRATION",
     "CUSTOM",
   ].includes(upper)
     ? upper
@@ -135,10 +279,21 @@ function validateManifest(m) {
     }
   }
 
+  // `actions` is optional (additive in SDK 1.8.0) — only validate when present.
+  if (manifest.actions !== undefined) {
+    validateManifestActions(manifest.actions, errors);
+  }
+
+  // `translations` is optional (additive in SDK 1.10.0 / REQ-L10N-WIDGET).
+  if (manifest.translations !== undefined) {
+    validateManifestTranslations(manifest.translations, manifest.id, errors);
+  }
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 
 module.exports = {
   validateManifest,
+  validateManifestTranslations,
   canonicalCategory,
 };

package/dist/manifest.js

@@ -5,11 +5,154 @@
 // 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;
+
+// REQ-L10N-WIDGET — caps + patterns for manifest-declared translations.
+// The relative key pattern is deliberately tighter than the dictionary's
+// own KEY_RE: once the host namespaces it (`widget.<id>.<key>`) the result
+// must still satisfy the dictionary cap (128 chars / KEY_RE in
+// backend/src/core/services/l10n.service.js). The locale pattern mirrors that
+// service's LANG_CODE_RE so a manifest can't declare a locale the dictionary
+// would reject.
+const TRANSLATIONS_MAX_KEYS = 100;
+const TRANSLATION_VALUE_MAX_BYTES = 1024;
+const TRANSLATION_KEY_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+const TRANSLATION_LOCALE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;
+const TRANSLATION_FULL_KEY_MAX = 128;
+
+function utf8ByteLength(s) {
+  return new TextEncoder().encode(s).length;
+}
+
+function validateManifestTranslations(translations, manifestId, errors) {
+  if (
+    translations === null ||
+    typeof translations !== "object" ||
+    Array.isArray(translations)
+  ) {
+    errors.push(
+      "manifest.translations must be an object mapping key -> { en, <locale>? }",
+    );
+    return;
+  }
+  const keys = Object.keys(translations);
+  if (keys.length > TRANSLATIONS_MAX_KEYS) {
+    errors.push(
+      `manifest.translations may declare at most ${TRANSLATIONS_MAX_KEYS} keys`,
+    );
+  }
+  for (const key of keys) {
+    if (!TRANSLATION_KEY_RE.test(key)) {
+      errors.push(
+        `manifest.translations key "${key}" must match /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/`,
+      );
+      continue;
+    }
+    if (isNonEmptyString(manifestId)) {
+      const fullKey = `widget.${manifestId}.${key}`;
+      if (fullKey.length > TRANSLATION_FULL_KEY_MAX) {
+        errors.push(
+          `manifest.translations key "${key}" is too long once namespaced (${fullKey.length} > ${TRANSLATION_FULL_KEY_MAX} chars)`,
+        );
+      }
+    }
+    const entry = translations[key];
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      errors.push(
+        `manifest.translations["${key}"] must be an object of locale -> string`,
+      );
+      continue;
+    }
+    if (!isNonEmptyString(entry.en)) {
+      errors.push(
+        `manifest.translations["${key}"].en is required and must be a non-empty string`,
+      );
+    }
+    for (const [locale, value] of Object.entries(entry)) {
+      if (!TRANSLATION_LOCALE_RE.test(locale)) {
+        errors.push(
+          `manifest.translations["${key}"] has invalid locale "${locale}"`,
+        );
+      }
+      if (typeof value !== "string") {
+        errors.push(
+          `manifest.translations["${key}"]["${locale}"] must be a string`,
+        );
+      } else if (utf8ByteLength(value) > TRANSLATION_VALUE_MAX_BYTES) {
+        errors.push(
+          `manifest.translations["${key}"]["${locale}"] exceeds 1 KB`,
+        );
+      }
+    }
+  }
+}
+
+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 +163,7 @@ function canonicalCategory(c) {
     "DATA",
     "MEDIA",
     "COMMUNICATION",
+    "ADMINISTRATION",
     "CUSTOM",
   ].includes(upper)
     ? upper
@@ -135,10 +279,21 @@ function validateManifest(m) {
     }
   }
 
+  // `actions` is optional (additive in SDK 1.8.0) — only validate when present.
+  if (manifest.actions !== undefined) {
+    validateManifestActions(manifest.actions, errors);
+  }
+
+  // `translations` is optional (additive in SDK 1.10.0 / REQ-L10N-WIDGET).
+  if (manifest.translations !== undefined) {
+    validateManifestTranslations(manifest.translations, manifest.id, errors);
+  }
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 
 export {
   validateManifest,
+  validateManifestTranslations,
   canonicalCategory,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.18.0",
+  "version": "0.21.1",
   "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 src/__tests__/widget-translations.test.js"
   },
   "engines": {
     "node": ">=18"