@cervio/plugin-core 1.0.1 → 1.3.0

package/dist/{browser-Ddj__JFI.d.ts → browser-CWGIdJMr.d.ts}

@@ -8,6 +8,13 @@
  * Example: `{ "path": "/api/v1/entities/attivita/records?limit=200" }`.
  * `/api/v1/entities/<technical name>/...` is accepted: the host also matches
  * the same path with the entity id the plugin may use.
+ *
+ * `{settings.<key>}` takes the value of one of the plugin's `settings`, filled
+ * by the host per organization (URL-encoded). Views are chosen per organization,
+ * so their id cannot be written in the manifest:
+ * `{ "path": "/api/v1/views/{settings.view_id}/records?limit=50" }`. When the
+ * setting is empty the host skips that entry and the plugin's call goes the
+ * normal way.
  */
 type PluginBootRequest = {
     /** Absolute path + optional query under `/api/v1/`, e.g. `/api/v1/entities/x/records?limit=50`. */

package/dist/browser.d.ts

@@ -1 +1 @@
-export { M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, a as PluginActionResult, g as PluginBootRequest, e as PluginCervioApiRequirement, i as PluginZip, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, x as readPluginZip } from './browser-Ddj__JFI.js';
+export { M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, a as PluginActionResult, g as PluginBootRequest, e as PluginCervioApiRequirement, i as PluginZip, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, x as readPluginZip } from './browser-CWGIdJMr.js';

package/dist/browser.js

@@ -145,10 +145,12 @@ function parsePluginCervioApiRequirements(raw) {
 // src/boot-requests.ts
 var MAX_PLUGIN_BOOT_REQUESTS = 8;
 var MAX_BOOT_PATH_LEN = 400;
+var SETTING_PLACEHOLDER_RE = /\{settings\.([A-Za-z0-9_]{1,64})\}/g;
+var PLACEHOLDER_PROBE = "x";
 function bootRequestPathname(path) {
   if (typeof path !== "string") return null;
-  const p = path.trim();
-  if (!p.startsWith("/api/v1/") || p.length > MAX_BOOT_PATH_LEN || p.includes("#")) return null;
+  const p = path.trim().replace(SETTING_PLACEHOLDER_RE, PLACEHOLDER_PROBE);
+  if (!p.startsWith("/api/v1/") || path.trim().length > MAX_BOOT_PATH_LEN || p.includes("#") || /[{}]/.test(p)) return null;
   const pathname = p.split("?")[0] ?? "";
   if (!isDeclarableCervioApiPrefix(pathname)) return null;
   return pathname;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as ParseManifestOptions, a as PluginActionResult, b as PluginType, c as PluginConnectionRequirement, d as PluginEntityRequirement, e as PluginCervioApiRequirement, f as PluginSettingsFieldRequirement, g as PluginBootRequest, h as ParsedPluginManifest, i as PluginZip } from './browser-Ddj__JFI.js';
-export { A as AllowedApiRule, D as DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES, E as ExternalConnectionHttpMethod, M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, l as PLUGIN_ARTIFACT_SOFT_STRONG_WARN_BYTES, m as PLUGIN_ARTIFACT_SOFT_WARN_BYTES, n as PLUGIN_KEY_RE, o as PluginEntityAccess, p as PluginSettingsFieldOption, q as PluginSettingsFieldType, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, w as parsePluginEntityRequirements, x as readPluginZip } from './browser-Ddj__JFI.js';
+import { P as ParseManifestOptions, a as PluginActionResult, b as PluginType, c as PluginConnectionRequirement, d as PluginEntityRequirement, e as PluginCervioApiRequirement, f as PluginSettingsFieldRequirement, g as PluginBootRequest, h as ParsedPluginManifest, i as PluginZip } from './browser-CWGIdJMr.js';
+export { A as AllowedApiRule, D as DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES, E as ExternalConnectionHttpMethod, M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, l as PLUGIN_ARTIFACT_SOFT_STRONG_WARN_BYTES, m as PLUGIN_ARTIFACT_SOFT_WARN_BYTES, n as PLUGIN_KEY_RE, o as PluginEntityAccess, p as PluginSettingsFieldOption, q as PluginSettingsFieldType, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, w as parsePluginEntityRequirements, x as readPluginZip } from './browser-CWGIdJMr.js';
 
 /**
  * Next patch version assigned by Cervio. Ignores pre-release/build metadata on
@@ -94,6 +94,15 @@ declare function parseZipManifest(file: Blob | ArrayBuffer | Uint8Array, options
 declare function computePluginContentSha256(zip: PluginZip, rawManifest: Record<string, unknown>): PluginActionResult<string>;
 declare function sha256Hex(buffer: Buffer | Uint8Array): string;
 
+/**
+ * Non-blocking advice from `validatePluginDir` on how fast the plugin opens.
+ * A plugin with hints is still valid and can be pushed.
+ */
+type PluginStartupHint = {
+    code: 'boot_requests_missing' | 'mark_ready_missing' | 'boot_request_hardcoded_view';
+    message: string;
+};
+
 type PackPluginResult = {
     buffer: Buffer;
     pluginKey: string;
@@ -108,10 +117,14 @@ declare function packPlugin(opts: {
     dir: string;
     options?: ParseManifestOptions;
 }): Promise<PluginActionResult<PackPluginResult>>;
-/** Validate an on-disk plugin directory (or an existing ZIP) without uploading. */
+/**
+ * Validate an on-disk plugin directory without uploading. `hints` is
+ * non-blocking advice on start-up speed (boot_requests, markReady).
+ */
 declare function validatePluginDir(dir: string, options?: ParseManifestOptions): Promise<PluginActionResult<{
     pluginKey: string;
     contentSha256: string;
+    hints: PluginStartupHint[];
 }>>;
 declare function validatePluginZipBuffer(buffer: Buffer, options?: ParseManifestOptions): Promise<PluginActionResult<{
     pluginKey: string;
@@ -119,4 +132,4 @@ declare function validatePluginZipBuffer(buffer: Buffer, options?: ParseManifest
 }>>;
 
 export { ParseManifestOptions, ParsedPluginManifest, PluginActionResult, PluginBootRequest, PluginCervioApiRequirement, PluginConnectionRequirement, PluginEntityRequirement, PluginSettingsFieldRequirement, PluginType, PluginZip, compareSemverDesc, computePluginContentSha256, isPolicyPluginType, manifestJsonForContentHash, nextPatchVersion, normalizePluginKey, normalizeToPolicyPluginType, packPlugin, parseManifestObject, parseZipManifest, sha256Hex, validatePluginDir, validatePluginZipBuffer };
-export type { PackPluginResult, PolicyHookCaller, PolicyHookEvent, PolicyHookInput, PolicyHookResult, PolicyHost };
+export type { PackPluginResult, PluginStartupHint, PolicyHookCaller, PolicyHookEvent, PolicyHookInput, PolicyHookResult, PolicyHost };

package/dist/index.js

@@ -139,15 +139,20 @@ function parsePluginCervioApiRequirements(raw) {
 // src/boot-requests.ts
 var MAX_PLUGIN_BOOT_REQUESTS = 8;
 var MAX_BOOT_PATH_LEN = 400;
+var SETTING_PLACEHOLDER_RE = /\{settings\.([A-Za-z0-9_]{1,64})\}/g;
+var PLACEHOLDER_PROBE = "x";
+function settingKeysOf(path2) {
+  return [...path2.matchAll(SETTING_PLACEHOLDER_RE)].map((m) => m[1]);
+}
 function bootRequestPathname(path2) {
   if (typeof path2 !== "string") return null;
-  const p = path2.trim();
-  if (!p.startsWith("/api/v1/") || p.length > MAX_BOOT_PATH_LEN || p.includes("#")) return null;
+  const p = path2.trim().replace(SETTING_PLACEHOLDER_RE, PLACEHOLDER_PROBE);
+  if (!p.startsWith("/api/v1/") || path2.trim().length > MAX_BOOT_PATH_LEN || p.includes("#") || /[{}]/.test(p)) return null;
   const pathname = p.split("?")[0] ?? "";
   if (!isDeclarableCervioApiPrefix(pathname)) return null;
   return pathname;
 }
-function validatePluginBootRequests(raw, cervioApis) {
+function validatePluginBootRequests(raw, cervioApis, settingKeys) {
   if (raw == null) return { ok: true, value: [] };
   if (!Array.isArray(raw)) return { ok: false, error: "manifest_boot_requests_invalid" };
   if (raw.length > MAX_PLUGIN_BOOT_REQUESTS) return { ok: false, error: "manifest_boot_requests_too_many" };
@@ -161,6 +166,9 @@ function validatePluginBootRequests(raw, cervioApis) {
       return { ok: false, error: "manifest_boot_requests_not_declared" };
     }
     const p = path2.trim();
+    if (settingKeys && settingKeysOf(p).some((k) => !settingKeys.includes(k))) {
+      return { ok: false, error: "manifest_boot_requests_unknown_setting" };
+    }
     if (seen.has(p)) continue;
     seen.add(p);
     out.push({ path: p });
@@ -523,7 +531,11 @@ function parseManifestObject(parsed, options) {
   if (!cervioApisRes.ok) return cervioApisRes;
   const cervioApis = cervioApisRes.value;
   const settings = parsePluginSettingsRequirements(parsed.settings);
-  const bootRequestsRes = validatePluginBootRequests(parsed.boot_requests, cervioApis);
+  const bootRequestsRes = validatePluginBootRequests(
+    parsed.boot_requests,
+    cervioApis,
+    settings.map((f) => f.key)
+  );
   if (!bootRequestsRes.ok) return bootRequestsRes;
   const bootRequests = bootRequestsRes.value;
   return {
@@ -622,6 +634,44 @@ function computePluginContentSha256(zip, rawManifest) {
 function sha256Hex(buffer) {
   return createHash("sha256").update(buffer).digest("hex");
 }
+
+// src/startup-hints.ts
+var ANSWERED_AT_BOOT = /* @__PURE__ */ new Set(["/api/v1/me", "/api/v1/entities"]);
+var MARK_READY_MARKER = "__cervioPluginReady";
+var VIEW_ID_IN_PATH = /\/api\/v1\/views\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\//i;
+var isIframePlugin = (t) => t === "route" || t === "task" || t === "task_form" || t === "form";
+function pluginStartupHints(input) {
+  if (!isIframePlugin(input.pluginType)) return [];
+  const hints = [];
+  const readsData = input.cervioApis.some(
+    (a) => a.method.toUpperCase() === "GET" && !ANSWERED_AT_BOOT.has(a.path_prefix)
+  );
+  if (input.pluginType === "route" && readsData && input.bootRequests.length === 0) {
+    hints.push({
+      code: "boot_requests_missing",
+      message: "No boot_requests: list the GET calls of the first screen in manifest.json (same path and query as the code). Cervio starts them while the plugin loads (measured: data on screen 350-500 ms sooner on the first open, 75-220 ms on later ones)."
+    });
+  }
+  if (!input.bundleText.includes(MARK_READY_MARKER)) {
+    hints.push({
+      code: "mark_ready_missing",
+      message: "markReady() is never called: call it from '@cervio/plugin-sdk' once the first data is on screen (also on error). Cervio keeps its loading skeleton until then and uses it to time the plugin open."
+    });
+  }
+  const viewKeys = input.settings.filter((s) => s.type === "string" && /view/i.test(s.key)).map((s) => s.key);
+  for (const b of input.bootRequests) {
+    const m = VIEW_ID_IN_PATH.exec(b.path);
+    if (!m) continue;
+    const placeholder = viewKeys.length ? `{settings.${viewKeys[0]}}` : "{settings.<key>}";
+    hints.push({
+      code: "boot_request_hardcoded_view",
+      message: `boot_requests path "${b.path}" has a fixed view id: write ${placeholder} instead` + (viewKeys.length ? "" : " and add a string setting for the view") + ", so the prefetch follows the view chosen in each organization."
+    });
+  }
+  return hints;
+}
+
+// src/pack.ts
 var ZIP_MTIME = /* @__PURE__ */ new Date("2000-01-01T00:00:00Z");
 async function collectFiles(dir, base = "") {
   const entries = await promises.readdir(dir, { withFileTypes: true });
@@ -717,16 +767,43 @@ async function packPlugin(opts) {
     }
   };
 }
+async function readBundleText(root) {
+  const dist = path.join(
+    /*turbopackIgnore: true*/
+    root,
+    "dist"
+  );
+  let files;
+  try {
+    files = await collectFiles(dist);
+  } catch {
+    return "";
+  }
+  const parts = [];
+  for (const f of files) {
+    if (/\.(m?js|html)$/i.test(f.rel)) parts.push(await promises.readFile(f.abs, "utf8"));
+  }
+  return parts.join("\n");
+}
 async function validatePluginDir(dir, options) {
   const packed = await packPlugin({ dir, options });
   if (!packed.ok) return packed;
   const parsed = await parseZipManifest(packed.value.buffer, options);
   if (!parsed.ok) return parsed;
+  const fields = parsed.value;
+  const hints = pluginStartupHints({
+    pluginType: fields.pluginType,
+    cervioApis: fields.cervioApis,
+    bootRequests: fields.bootRequests,
+    settings: fields.settings,
+    bundleText: isPolicyPluginType(fields.pluginType) ? "" : await readBundleText(path.resolve(dir))
+  });
   return {
     ok: true,
     value: {
       pluginKey: packed.value.pluginKey,
-      contentSha256: packed.value.contentSha256
+      contentSha256: packed.value.contentSha256,
+      hints
     }
   };
 }

package/manifest.schema.json

@@ -220,7 +220,7 @@
             "properties": {
               "path": {
                 "type": "string",
-                "description": "GET path + optional query under /api/v1/, covered by a GET `cervio_apis` prefix."
+                "description": "GET path + optional query under /api/v1/, covered by a GET `cervio_apis` prefix. `{settings.<key>}` takes a plugin setting (e.g. /api/v1/views/{settings.view_id}/records?limit=50)."
               }
             },
             "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cervio/plugin-core",
-  "version": "1.0.1",
+  "version": "1.3.0",
   "description": "Shared Cervio plugin manifest validation, ZIP safety, content hash, and packing.",
   "keywords": [
     "cervio",