@vivoa/plugin-sdk 0.6.5 → 0.6.6

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ANALYTICS_PLUGIN_TOKEN: () => ANALYTICS_PLUGIN_TOKEN,
+  AUTHOR_HANDLE_RE: () => AUTHOR_HANDLE_RE,
   ActionVariant: () => ActionVariant,
   AnalyticsFeature: () => AnalyticsFeature,
   BlockType: () => BlockType,
@@ -62,6 +63,7 @@ __export(index_exports, {
   paymentCapability: () => paymentCapability,
   shippingCapability: () => shippingCapability,
   suppliersCapability: () => suppliersCapability,
+  validatePluginAuthor: () => validatePluginAuthor,
   validateSetupLayout: () => validateSetupLayout
 });
 module.exports = __toCommonJS(index_exports);
@@ -244,6 +246,30 @@ var InvoiceStatus = /* @__PURE__ */ ((InvoiceStatus2) => {
   return InvoiceStatus2;
 })(InvoiceStatus || {});
 
+// src/author.ts
+var AUTHOR_HANDLE_RE = /^[a-z0-9][a-z0-9-]*$/;
+function validatePluginAuthor(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) {
+    return { ok: false, errors: ["author is required and must be an object"] };
+  }
+  const a = value;
+  if (typeof a.handle !== "string" || a.handle.length === 0) {
+    errors.push("author.handle is required");
+  } else if (!AUTHOR_HANDLE_RE.test(a.handle)) {
+    errors.push(
+      `author.handle "${a.handle}" must be a lowercase slug (a-z, 0-9, dash; start alphanumeric)`
+    );
+  }
+  if (typeof a.displayName !== "string" || a.displayName.trim().length === 0) {
+    errors.push("author.displayName is required");
+  }
+  if (a.url !== void 0 && typeof a.url !== "string") {
+    errors.push("author.url must be a string when present");
+  }
+  return { ok: errors.length === 0, errors };
+}
+
 // src/setup-layout.ts
 var import_superstruct2 = require("superstruct");
 var FieldVariant = /* @__PURE__ */ ((FieldVariant2) => {
@@ -581,7 +607,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.6.5";
+var SDK_VERSION = "0.6.6";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -599,6 +625,7 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ANALYTICS_PLUGIN_TOKEN,
+  AUTHOR_HANDLE_RE,
   ActionVariant,
   AnalyticsFeature,
   BlockType,
@@ -640,5 +667,6 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   paymentCapability,
   shippingCapability,
   suppliersCapability,
+  validatePluginAuthor,
   validateSetupLayout
 });

package/dist/index.mjs

@@ -1,3 +1,9 @@
+import {
+  checkPermissions,
+  isPermissionGranted,
+  parsePermission
+} from "./chunk-DGJZW46B.mjs";
+
 // src/tokens.ts
 var PAYMENT_PLUGIN_TOKEN = "PAYMENT_PLUGINS";
 var SHIPPING_PLUGIN_TOKEN = "SHIPPING_PLUGINS";
@@ -184,6 +190,30 @@ var InvoiceStatus = /* @__PURE__ */ ((InvoiceStatus2) => {
   return InvoiceStatus2;
 })(InvoiceStatus || {});
 
+// src/author.ts
+var AUTHOR_HANDLE_RE = /^[a-z0-9][a-z0-9-]*$/;
+function validatePluginAuthor(value) {
+  const errors = [];
+  if (typeof value !== "object" || value === null) {
+    return { ok: false, errors: ["author is required and must be an object"] };
+  }
+  const a = value;
+  if (typeof a.handle !== "string" || a.handle.length === 0) {
+    errors.push("author.handle is required");
+  } else if (!AUTHOR_HANDLE_RE.test(a.handle)) {
+    errors.push(
+      `author.handle "${a.handle}" must be a lowercase slug (a-z, 0-9, dash; start alphanumeric)`
+    );
+  }
+  if (typeof a.displayName !== "string" || a.displayName.trim().length === 0) {
+    errors.push("author.displayName is required");
+  }
+  if (a.url !== void 0 && typeof a.url !== "string") {
+    errors.push("author.url must be a string when present");
+  }
+  return { ok: errors.length === 0, errors };
+}
+
 // src/setup-layout.ts
 import {
   array,
@@ -501,40 +531,8 @@ function isPluginFactory(value) {
   return typeof value === "function" && value[PLUGIN_FACTORY_BRAND] === true;
 }
 
-// src/permissions.ts
-var PERMISSION_RE = /^([a-z0-9]+)\.([a-z0-9]+)(?::(.+))?$/i;
-function parsePermission(raw) {
-  const m = PERMISSION_RE.exec(raw);
-  if (!m) return null;
-  const [, domain, action, resource] = m;
-  return resource === void 0 ? { domain, action } : { domain, action, resource };
-}
-function isPermissionGranted(required, granted) {
-  return granted.some((g) => {
-    if (g.domain !== required.domain || g.action !== required.action) {
-      return false;
-    }
-    if (required.resource === void 0) return true;
-    return g.resource === "*" || g.resource === required.resource;
-  });
-}
-function checkPermissions(required, grantedRaw) {
-  const grantedParsed = grantedRaw.map(parsePermission).filter((p) => p !== null);
-  const granted = [];
-  const missing = [];
-  for (const raw of required) {
-    const parsed = parsePermission(raw);
-    if (parsed && isPermissionGranted(parsed, grantedParsed)) {
-      granted.push(raw);
-    } else {
-      missing.push(raw);
-    }
-  }
-  return { ok: missing.length === 0, granted, missing };
-}
-
 // src/version.ts
-var SDK_VERSION = "0.6.5";
+var SDK_VERSION = "0.6.6";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -551,6 +549,7 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
 }
 export {
   ANALYTICS_PLUGIN_TOKEN,
+  AUTHOR_HANDLE_RE,
   ActionVariant,
   AnalyticsFeature,
   BlockType,
@@ -592,5 +591,6 @@ export {
   paymentCapability,
   shippingCapability,
   suppliersCapability,
+  validatePluginAuthor,
   validateSetupLayout
 };

package/dist/testing/index.d.mts

@@ -0,0 +1,54 @@
+import { X as HostApi, Z as HttpRequest, N as DomainEventName, u as Capability, M as DomainEventHandler, _ as HttpResponse, K as DispatchContext } from '../host-api-C1VylW5l.mjs';
+
+/** Every recorded interaction, keyed by `"port.method"`. */
+interface MockHostCalls {
+    'http.request': HttpRequest[];
+    'secrets.get': string[];
+    'storage.getUrl': string[];
+    'storage.put': Array<{
+        key: string;
+        body: Uint8Array | string;
+    }>;
+    'sequence.next': string[];
+    'host.on': DomainEventName[];
+}
+interface MockHostOptions {
+    /**
+     * Permissions the mock "grants". When set, the mock enforces them exactly as
+     * the real host is specified to: an un-granted `http.outbound:<host>` or
+     * `secrets.read:<key>` THROWS. Omit to grant everything (pure recorder mode).
+     */
+    grantedPermissions?: string[];
+    /** Canned secret values returned by `secrets.get`. */
+    secrets?: Record<string, string>;
+    /**
+     * Canned HTTP responses. Resolved against the request URL — exact match
+     * first, then the first entry whose key is a substring of the URL. Defaults
+     * to `{ status: 200, headers: {}, body: {} }`.
+     */
+    httpResponses?: Record<string, HttpResponse>;
+    /** Seed values for named sequence scopes (monotonic from here). */
+    sequences?: Record<string, number>;
+}
+interface MockHostApi extends HostApi {
+    /** Every port call recorded in order. */
+    readonly calls: MockHostCalls;
+    /** Capabilities the plugin registered via `registerCapability`. */
+    readonly registered: Capability[];
+    /** Event handlers the plugin subscribed via `host.on`. */
+    readonly handlers: Map<DomainEventName, DomainEventHandler[]>;
+    /** Drives a subscribed handler as if the host emitted the event. */
+    emit(event: DomainEventName, payload: unknown): Promise<void>;
+}
+/**
+ * Builds a {@link MockHostApi}. Pass `grantedPermissions` to assert your plugin
+ * declared what it actually uses; leave it out to just record calls.
+ */
+declare function createMockHostApi(opts?: MockHostOptions): MockHostApi;
+/**
+ * Minimal {@link DispatchContext} for dispatch-method tests. Pass the merged
+ * config your plugin expects; the country fields mirror the host's resolution.
+ */
+declare function createDispatchContext(config?: Record<string, unknown>, overrides?: Partial<DispatchContext>): DispatchContext;
+
+export { type MockHostApi, type MockHostCalls, type MockHostOptions, createDispatchContext, createMockHostApi };

package/dist/testing/index.d.ts

@@ -0,0 +1,54 @@
+import { X as HostApi, Z as HttpRequest, N as DomainEventName, u as Capability, M as DomainEventHandler, _ as HttpResponse, K as DispatchContext } from '../host-api-C1VylW5l.js';
+
+/** Every recorded interaction, keyed by `"port.method"`. */
+interface MockHostCalls {
+    'http.request': HttpRequest[];
+    'secrets.get': string[];
+    'storage.getUrl': string[];
+    'storage.put': Array<{
+        key: string;
+        body: Uint8Array | string;
+    }>;
+    'sequence.next': string[];
+    'host.on': DomainEventName[];
+}
+interface MockHostOptions {
+    /**
+     * Permissions the mock "grants". When set, the mock enforces them exactly as
+     * the real host is specified to: an un-granted `http.outbound:<host>` or
+     * `secrets.read:<key>` THROWS. Omit to grant everything (pure recorder mode).
+     */
+    grantedPermissions?: string[];
+    /** Canned secret values returned by `secrets.get`. */
+    secrets?: Record<string, string>;
+    /**
+     * Canned HTTP responses. Resolved against the request URL — exact match
+     * first, then the first entry whose key is a substring of the URL. Defaults
+     * to `{ status: 200, headers: {}, body: {} }`.
+     */
+    httpResponses?: Record<string, HttpResponse>;
+    /** Seed values for named sequence scopes (monotonic from here). */
+    sequences?: Record<string, number>;
+}
+interface MockHostApi extends HostApi {
+    /** Every port call recorded in order. */
+    readonly calls: MockHostCalls;
+    /** Capabilities the plugin registered via `registerCapability`. */
+    readonly registered: Capability[];
+    /** Event handlers the plugin subscribed via `host.on`. */
+    readonly handlers: Map<DomainEventName, DomainEventHandler[]>;
+    /** Drives a subscribed handler as if the host emitted the event. */
+    emit(event: DomainEventName, payload: unknown): Promise<void>;
+}
+/**
+ * Builds a {@link MockHostApi}. Pass `grantedPermissions` to assert your plugin
+ * declared what it actually uses; leave it out to just record calls.
+ */
+declare function createMockHostApi(opts?: MockHostOptions): MockHostApi;
+/**
+ * Minimal {@link DispatchContext} for dispatch-method tests. Pass the merged
+ * config your plugin expects; the country fields mirror the host's resolution.
+ */
+declare function createDispatchContext(config?: Record<string, unknown>, overrides?: Partial<DispatchContext>): DispatchContext;
+
+export { type MockHostApi, type MockHostCalls, type MockHostOptions, createDispatchContext, createMockHostApi };

package/dist/testing/index.js

@@ -0,0 +1,169 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing/index.ts
+var testing_exports = {};
+__export(testing_exports, {
+  createDispatchContext: () => createDispatchContext,
+  createMockHostApi: () => createMockHostApi
+});
+module.exports = __toCommonJS(testing_exports);
+
+// src/permissions.ts
+var PERMISSION_RE = /^([a-z0-9]+)\.([a-z0-9]+)(?::(.+))?$/i;
+function parsePermission(raw) {
+  const m = PERMISSION_RE.exec(raw);
+  if (!m) return null;
+  const [, domain, action, resource] = m;
+  return resource === void 0 ? { domain, action } : { domain, action, resource };
+}
+function isPermissionGranted(required, granted) {
+  return granted.some((g) => {
+    if (g.domain !== required.domain || g.action !== required.action) {
+      return false;
+    }
+    if (required.resource === void 0) return true;
+    return g.resource === "*" || g.resource === required.resource;
+  });
+}
+function checkPermissions(required, grantedRaw) {
+  const grantedParsed = grantedRaw.map(parsePermission).filter((p) => p !== null);
+  const granted = [];
+  const missing = [];
+  for (const raw of required) {
+    const parsed = parsePermission(raw);
+    if (parsed && isPermissionGranted(parsed, grantedParsed)) {
+      granted.push(raw);
+    } else {
+      missing.push(raw);
+    }
+  }
+  return { ok: missing.length === 0, granted, missing };
+}
+
+// src/testing/mock-host.ts
+var DEFAULT_RESPONSE = { status: 200, headers: {}, body: {} };
+function createMockHostApi(opts = {}) {
+  const calls = {
+    "http.request": [],
+    "secrets.get": [],
+    "storage.getUrl": [],
+    "storage.put": [],
+    "sequence.next": [],
+    "host.on": []
+  };
+  const registered = [];
+  const handlers = /* @__PURE__ */ new Map();
+  const seqState = new Map(
+    Object.entries(opts.sequences ?? {})
+  );
+  const enforce = (required) => {
+    if (!opts.grantedPermissions) return;
+    const check = checkPermissions([required], opts.grantedPermissions);
+    if (!check.ok) {
+      throw new Error(
+        `MockHostApi: permission denied \u2014 plugin needs "${required}" but it is not in grantedPermissions. Declare it in your manifest.`
+      );
+    }
+  };
+  const noop = () => {
+  };
+  const logger = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop
+  };
+  const http = {
+    // async so a denied-permission throw surfaces as a rejected promise, not a
+    // synchronous throw — matches the real host's async port contract.
+    request: async (req) => {
+      const hostname = safeHostname(req.url);
+      enforce(`http.outbound:${hostname}`);
+      calls["http.request"].push(req);
+      return opts.httpResponses?.[req.url] ?? Object.entries(opts.httpResponses ?? {}).find(
+        ([k]) => req.url.includes(k)
+      )?.[1] ?? DEFAULT_RESPONSE;
+    }
+  };
+  const secrets = {
+    get: async (key) => {
+      enforce(`secrets.read:${key}`);
+      calls["secrets.get"].push(key);
+      return opts.secrets?.[key];
+    }
+  };
+  const storage = {
+    getUrl: (key) => {
+      calls["storage.getUrl"].push(key);
+      return Promise.resolve(`mock://storage/${key}`);
+    },
+    put: (key, body) => {
+      calls["storage.put"].push({ key, body });
+      return Promise.resolve();
+    }
+  };
+  const sequence = {
+    next: (scope) => {
+      calls["sequence.next"].push(scope);
+      const current = seqState.get(scope) ?? 0;
+      const next = current + 1;
+      seqState.set(scope, next);
+      return Promise.resolve(next);
+    }
+  };
+  const host = {
+    logger,
+    http,
+    secrets,
+    storage,
+    sequence,
+    calls,
+    registered,
+    handlers,
+    on: (event, handler) => {
+      calls["host.on"].push(event);
+      const list = handlers.get(event) ?? [];
+      list.push(handler);
+      handlers.set(event, list);
+    },
+    registerCapability: (cap) => {
+      registered.push(cap);
+    },
+    emit: async (event, payload) => {
+      for (const h of handlers.get(event) ?? []) await h(payload);
+    }
+  };
+  return host;
+}
+function safeHostname(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return url;
+  }
+}
+function createDispatchContext(config = {}, overrides = {}) {
+  return { config, ...overrides };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDispatchContext,
+  createMockHostApi
+});

package/dist/testing/index.mjs

@@ -0,0 +1,113 @@
+import {
+  checkPermissions
+} from "../chunk-DGJZW46B.mjs";
+
+// src/testing/mock-host.ts
+var DEFAULT_RESPONSE = { status: 200, headers: {}, body: {} };
+function createMockHostApi(opts = {}) {
+  const calls = {
+    "http.request": [],
+    "secrets.get": [],
+    "storage.getUrl": [],
+    "storage.put": [],
+    "sequence.next": [],
+    "host.on": []
+  };
+  const registered = [];
+  const handlers = /* @__PURE__ */ new Map();
+  const seqState = new Map(
+    Object.entries(opts.sequences ?? {})
+  );
+  const enforce = (required) => {
+    if (!opts.grantedPermissions) return;
+    const check = checkPermissions([required], opts.grantedPermissions);
+    if (!check.ok) {
+      throw new Error(
+        `MockHostApi: permission denied \u2014 plugin needs "${required}" but it is not in grantedPermissions. Declare it in your manifest.`
+      );
+    }
+  };
+  const noop = () => {
+  };
+  const logger = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop
+  };
+  const http = {
+    // async so a denied-permission throw surfaces as a rejected promise, not a
+    // synchronous throw — matches the real host's async port contract.
+    request: async (req) => {
+      const hostname = safeHostname(req.url);
+      enforce(`http.outbound:${hostname}`);
+      calls["http.request"].push(req);
+      return opts.httpResponses?.[req.url] ?? Object.entries(opts.httpResponses ?? {}).find(
+        ([k]) => req.url.includes(k)
+      )?.[1] ?? DEFAULT_RESPONSE;
+    }
+  };
+  const secrets = {
+    get: async (key) => {
+      enforce(`secrets.read:${key}`);
+      calls["secrets.get"].push(key);
+      return opts.secrets?.[key];
+    }
+  };
+  const storage = {
+    getUrl: (key) => {
+      calls["storage.getUrl"].push(key);
+      return Promise.resolve(`mock://storage/${key}`);
+    },
+    put: (key, body) => {
+      calls["storage.put"].push({ key, body });
+      return Promise.resolve();
+    }
+  };
+  const sequence = {
+    next: (scope) => {
+      calls["sequence.next"].push(scope);
+      const current = seqState.get(scope) ?? 0;
+      const next = current + 1;
+      seqState.set(scope, next);
+      return Promise.resolve(next);
+    }
+  };
+  const host = {
+    logger,
+    http,
+    secrets,
+    storage,
+    sequence,
+    calls,
+    registered,
+    handlers,
+    on: (event, handler) => {
+      calls["host.on"].push(event);
+      const list = handlers.get(event) ?? [];
+      list.push(handler);
+      handlers.set(event, list);
+    },
+    registerCapability: (cap) => {
+      registered.push(cap);
+    },
+    emit: async (event, payload) => {
+      for (const h of handlers.get(event) ?? []) await h(payload);
+    }
+  };
+  return host;
+}
+function safeHostname(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return url;
+  }
+}
+function createDispatchContext(config = {}, overrides = {}) {
+  return { config, ...overrides };
+}
+export {
+  createDispatchContext,
+  createMockHostApi
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivoa/plugin-sdk",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Public contracts for Vivoa plugins (types, DI tokens, config + setup-layout validators)",
   "license": "MIT",
   "author": "Vivoa",
@@ -24,6 +24,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.mjs",
+      "require": "./dist/testing/index.js"
     }
   },
   "sideEffects": false,
@@ -44,8 +49,8 @@
     "vitest": "^2.1.8"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean --target node18",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --target node18",
+    "build": "tsup src/index.ts src/testing/index.ts --format cjs,esm --dts --clean --target node18",
+    "dev": "tsup src/index.ts src/testing/index.ts --format cjs,esm --dts --watch --target node18",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json"