@vivoa/plugin-sdk 0.6.5 → 0.6.7

package/dist/index.js

@@ -21,12 +21,15 @@ 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,
   CapabilityKind: () => CapabilityKind,
   CodFeeType: () => CodFeeType,
   ConfigScope: () => ConfigScope,
+  ContentActionVariant: () => ContentActionVariant,
+  ContentBlockType: () => ContentBlockType,
   FieldType: () => FieldType,
   FieldVariant: () => FieldVariant,
   GatewayEnvironment: () => GatewayEnvironment,
@@ -37,7 +40,6 @@ __export(index_exports, {
   LayoutMode: () => LayoutMode,
   MessageVariant: () => MessageVariant,
   PAYMENT_PLUGIN_TOKEN: () => PAYMENT_PLUGIN_TOKEN,
-  PluginType: () => PluginType,
   RepeaterSource: () => RepeaterSource,
   SDK_VERSION: () => SDK_VERSION,
   SHIPPING_PLUGIN_TOKEN: () => SHIPPING_PLUGIN_TOKEN,
@@ -62,7 +64,10 @@ __export(index_exports, {
   paymentCapability: () => paymentCapability,
   shippingCapability: () => shippingCapability,
   suppliersCapability: () => suppliersCapability,
-  validateSetupLayout: () => validateSetupLayout
+  uiCapability: () => uiCapability,
+  validatePluginAuthor: () => validatePluginAuthor,
+  validateSetupLayout: () => validateSetupLayout,
+  validateUiContributions: () => validateUiContributions
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -74,14 +79,6 @@ var ANALYTICS_PLUGIN_TOKEN = "ANALYTICS_PLUGINS";
 var INVOICING_PLUGIN_TOKEN = "INVOICING_PLUGINS";
 
 // src/plugin.ts
-var PluginType = /* @__PURE__ */ ((PluginType2) => {
-  PluginType2["Payment"] = "payment";
-  PluginType2["Shipping"] = "shipping";
-  PluginType2["Analytics"] = "analytics";
-  PluginType2["Invoicing"] = "invoicing";
-  PluginType2["Generic"] = "generic";
-  return PluginType2;
-})(PluginType || {});
 var MessageVariant = /* @__PURE__ */ ((MessageVariant2) => {
   MessageVariant2["Info"] = "info";
   MessageVariant2["Warning"] = "warning";
@@ -244,6 +241,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) => {
@@ -314,6 +335,7 @@ var sGroupBlock = (0, import_superstruct2.object)({
   type: (0, import_superstruct2.literal)("group" /* Group */),
   title: (0, import_superstruct2.string)(),
   description: (0, import_superstruct2.optional)((0, import_superstruct2.string)()),
+  helpUrl: (0, import_superstruct2.optional)((0, import_superstruct2.string)()),
   fields: (0, import_superstruct2.array)((0, import_superstruct2.string)()),
   collapsible: (0, import_superstruct2.optional)((0, import_superstruct2.boolean)()),
   defaultOpen: (0, import_superstruct2.optional)((0, import_superstruct2.boolean)()),
@@ -510,13 +532,124 @@ function crossValidateSetupLayout(layout, configSchema) {
   return errors;
 }
 
+// src/ui.ts
+var import_superstruct3 = require("superstruct");
+var ContentBlockType = /* @__PURE__ */ ((ContentBlockType2) => {
+  ContentBlockType2["Text"] = "text";
+  ContentBlockType2["Banner"] = "banner";
+  ContentBlockType2["Badge"] = "badge";
+  ContentBlockType2["KeyValue"] = "keyValue";
+  ContentBlockType2["CopyField"] = "copyField";
+  ContentBlockType2["Link"] = "link";
+  ContentBlockType2["Divider"] = "divider";
+  ContentBlockType2["Action"] = "action";
+  ContentBlockType2["Card"] = "card";
+  return ContentBlockType2;
+})(ContentBlockType || {});
+var ContentActionVariant = /* @__PURE__ */ ((ContentActionVariant2) => {
+  ContentActionVariant2["Primary"] = "primary";
+  ContentActionVariant2["Secondary"] = "secondary";
+  ContentActionVariant2["Danger"] = "danger";
+  return ContentActionVariant2;
+})(ContentActionVariant || {});
+var sMessageVariant2 = (0, import_superstruct3.enums)(Object.values(MessageVariant));
+var sContentActionVariant = (0, import_superstruct3.enums)(Object.values(ContentActionVariant));
+var sTextBlock = (0, import_superstruct3.object)({
+  type: (0, import_superstruct3.literal)("text" /* Text */),
+  content: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+  computedKey: (0, import_superstruct3.optional)((0, import_superstruct3.string)())
+});
+var sBannerBlock2 = (0, import_superstruct3.object)({
+  type: (0, import_superstruct3.literal)("banner" /* Banner */),
+  variant: sMessageVariant2,
+  title: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+  text: (0, import_superstruct3.string)()
+});
+var sBadgeBlock = (0, import_superstruct3.object)({
+  type: (0, import_superstruct3.literal)("badge" /* Badge */),
+  variant: sMessageVariant2,
+  text: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+  computedKey: (0, import_superstruct3.optional)((0, import_superstruct3.string)())
+});
+var sKeyValueBlock2 = (0, import_superstruct3.object)({
+  type: (0, import_superstruct3.literal)("keyValue" /* KeyValue */),
+  rows: (0, import_superstruct3.array)(
+    (0, import_superstruct3.object)({
+      label: (0, import_superstruct3.string)(),
+      value: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+      computedKey: (0, import_superstruct3.optional)((0, import_superstruct3.string)())
+    })
+  )
+});
+var sCopyFieldBlock2 = (0, import_superstruct3.object)({
+  type: (0, import_superstruct3.literal)("copyField" /* CopyField */),
+  label: (0, import_superstruct3.string)(),
+  value: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+  computedKey: (0, import_superstruct3.optional)((0, import_superstruct3.string)())
+});
+var sLinkBlock = (0, import_superstruct3.object)({
+  type: (0, import_superstruct3.literal)("link" /* Link */),
+  label: (0, import_superstruct3.string)(),
+  href: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+  computedKey: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+  external: (0, import_superstruct3.optional)((0, import_superstruct3.boolean)())
+});
+var sDividerBlock2 = (0, import_superstruct3.object)({ type: (0, import_superstruct3.literal)("divider" /* Divider */) });
+var sActionBlock2 = (0, import_superstruct3.object)({
+  type: (0, import_superstruct3.literal)("action" /* Action */),
+  id: (0, import_superstruct3.string)(),
+  label: (0, import_superstruct3.string)(),
+  variant: (0, import_superstruct3.optional)(sContentActionVariant)
+});
+var sCardBlock2 = (0, import_superstruct3.object)({
+  type: (0, import_superstruct3.literal)("card" /* Card */),
+  title: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+  description: (0, import_superstruct3.optional)((0, import_superstruct3.string)()),
+  blocks: (0, import_superstruct3.array)((0, import_superstruct3.lazy)(() => sContentBlock))
+});
+var sContentBlock = (0, import_superstruct3.union)([
+  sTextBlock,
+  sBannerBlock2,
+  sBadgeBlock,
+  sKeyValueBlock2,
+  sCopyFieldBlock2,
+  sLinkBlock,
+  sDividerBlock2,
+  sActionBlock2,
+  sCardBlock2
+]);
+var sUiContribution = (0, import_superstruct3.object)({
+  slot: (0, import_superstruct3.string)(),
+  blocks: (0, import_superstruct3.array)(sContentBlock),
+  order: (0, import_superstruct3.optional)((0, import_superstruct3.number)())
+});
+function validateUiContributions(input) {
+  const [error, result] = (0, import_superstruct3.validate)(input, (0, import_superstruct3.array)(sUiContribution));
+  if (error) {
+    return {
+      success: false,
+      errors: error.failures().map((f) => {
+        const path = f.path.join(".");
+        return path ? `${path}: ${f.message}` : f.message;
+      })
+    };
+  }
+  return { success: true, data: result };
+}
+
 // src/capability.ts
 var CapabilityKind = {
   Payment: "payment",
   Shipping: "shipping",
   Suppliers: "suppliers",
   Analytics: "analytics",
-  Invoicing: "invoicing"
+  Invoicing: "invoicing",
+  /**
+   * Cross-cutting DISPLAY capability: a plugin of ANY surface may ALSO expose
+   * `ui` to contribute declarative blocks into host slots. Not a catalog
+   * "surface" — the host's AppSurface derivation excludes it on purpose.
+   */
+  Ui: "ui"
 };
 function capability(kind, impl) {
   return { kind, impl };
@@ -536,6 +669,9 @@ function analyticsCapability(impl) {
 function invoicingCapability(impl) {
   return { kind: CapabilityKind.Invoicing, impl };
 }
+function uiCapability(impl) {
+  return { kind: CapabilityKind.Ui, impl };
+}
 var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
 function definePlugin(factory) {
   Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
@@ -581,7 +717,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.6.5";
+var SDK_VERSION = "0.6.7";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -599,12 +735,15 @@ 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,
   CapabilityKind,
   CodFeeType,
   ConfigScope,
+  ContentActionVariant,
+  ContentBlockType,
   FieldType,
   FieldVariant,
   GatewayEnvironment,
@@ -615,7 +754,6 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   LayoutMode,
   MessageVariant,
   PAYMENT_PLUGIN_TOKEN,
-  PluginType,
   RepeaterSource,
   SDK_VERSION,
   SHIPPING_PLUGIN_TOKEN,
@@ -640,5 +778,8 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   paymentCapability,
   shippingCapability,
   suppliersCapability,
-  validateSetupLayout
+  uiCapability,
+  validatePluginAuthor,
+  validateSetupLayout,
+  validateUiContributions
 });

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";
@@ -6,14 +12,6 @@ var ANALYTICS_PLUGIN_TOKEN = "ANALYTICS_PLUGINS";
 var INVOICING_PLUGIN_TOKEN = "INVOICING_PLUGINS";
 
 // src/plugin.ts
-var PluginType = /* @__PURE__ */ ((PluginType2) => {
-  PluginType2["Payment"] = "payment";
-  PluginType2["Shipping"] = "shipping";
-  PluginType2["Analytics"] = "analytics";
-  PluginType2["Invoicing"] = "invoicing";
-  PluginType2["Generic"] = "generic";
-  return PluginType2;
-})(PluginType || {});
 var MessageVariant = /* @__PURE__ */ ((MessageVariant2) => {
   MessageVariant2["Info"] = "info";
   MessageVariant2["Warning"] = "warning";
@@ -184,6 +182,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,
@@ -267,6 +289,7 @@ var sGroupBlock = object({
   type: literal("group" /* Group */),
   title: string2(),
   description: optional2(string2()),
+  helpUrl: optional2(string2()),
   fields: array(string2()),
   collapsible: optional2(boolean2()),
   defaultOpen: optional2(boolean2()),
@@ -463,13 +486,136 @@ function crossValidateSetupLayout(layout, configSchema) {
   return errors;
 }
 
+// src/ui.ts
+import {
+  array as array2,
+  boolean as boolean3,
+  enums as enums3,
+  lazy as lazy2,
+  literal as literal2,
+  number as number3,
+  object as object2,
+  optional as optional3,
+  string as string3,
+  union as union2,
+  validate as validate3
+} from "superstruct";
+var ContentBlockType = /* @__PURE__ */ ((ContentBlockType2) => {
+  ContentBlockType2["Text"] = "text";
+  ContentBlockType2["Banner"] = "banner";
+  ContentBlockType2["Badge"] = "badge";
+  ContentBlockType2["KeyValue"] = "keyValue";
+  ContentBlockType2["CopyField"] = "copyField";
+  ContentBlockType2["Link"] = "link";
+  ContentBlockType2["Divider"] = "divider";
+  ContentBlockType2["Action"] = "action";
+  ContentBlockType2["Card"] = "card";
+  return ContentBlockType2;
+})(ContentBlockType || {});
+var ContentActionVariant = /* @__PURE__ */ ((ContentActionVariant2) => {
+  ContentActionVariant2["Primary"] = "primary";
+  ContentActionVariant2["Secondary"] = "secondary";
+  ContentActionVariant2["Danger"] = "danger";
+  return ContentActionVariant2;
+})(ContentActionVariant || {});
+var sMessageVariant2 = enums3(Object.values(MessageVariant));
+var sContentActionVariant = enums3(Object.values(ContentActionVariant));
+var sTextBlock = object2({
+  type: literal2("text" /* Text */),
+  content: optional3(string3()),
+  computedKey: optional3(string3())
+});
+var sBannerBlock2 = object2({
+  type: literal2("banner" /* Banner */),
+  variant: sMessageVariant2,
+  title: optional3(string3()),
+  text: string3()
+});
+var sBadgeBlock = object2({
+  type: literal2("badge" /* Badge */),
+  variant: sMessageVariant2,
+  text: optional3(string3()),
+  computedKey: optional3(string3())
+});
+var sKeyValueBlock2 = object2({
+  type: literal2("keyValue" /* KeyValue */),
+  rows: array2(
+    object2({
+      label: string3(),
+      value: optional3(string3()),
+      computedKey: optional3(string3())
+    })
+  )
+});
+var sCopyFieldBlock2 = object2({
+  type: literal2("copyField" /* CopyField */),
+  label: string3(),
+  value: optional3(string3()),
+  computedKey: optional3(string3())
+});
+var sLinkBlock = object2({
+  type: literal2("link" /* Link */),
+  label: string3(),
+  href: optional3(string3()),
+  computedKey: optional3(string3()),
+  external: optional3(boolean3())
+});
+var sDividerBlock2 = object2({ type: literal2("divider" /* Divider */) });
+var sActionBlock2 = object2({
+  type: literal2("action" /* Action */),
+  id: string3(),
+  label: string3(),
+  variant: optional3(sContentActionVariant)
+});
+var sCardBlock2 = object2({
+  type: literal2("card" /* Card */),
+  title: optional3(string3()),
+  description: optional3(string3()),
+  blocks: array2(lazy2(() => sContentBlock))
+});
+var sContentBlock = union2([
+  sTextBlock,
+  sBannerBlock2,
+  sBadgeBlock,
+  sKeyValueBlock2,
+  sCopyFieldBlock2,
+  sLinkBlock,
+  sDividerBlock2,
+  sActionBlock2,
+  sCardBlock2
+]);
+var sUiContribution = object2({
+  slot: string3(),
+  blocks: array2(sContentBlock),
+  order: optional3(number3())
+});
+function validateUiContributions(input) {
+  const [error, result] = validate3(input, array2(sUiContribution));
+  if (error) {
+    return {
+      success: false,
+      errors: error.failures().map((f) => {
+        const path = f.path.join(".");
+        return path ? `${path}: ${f.message}` : f.message;
+      })
+    };
+  }
+  return { success: true, data: result };
+}
+
 // src/capability.ts
 var CapabilityKind = {
   Payment: "payment",
   Shipping: "shipping",
   Suppliers: "suppliers",
   Analytics: "analytics",
-  Invoicing: "invoicing"
+  Invoicing: "invoicing",
+  /**
+   * Cross-cutting DISPLAY capability: a plugin of ANY surface may ALSO expose
+   * `ui` to contribute declarative blocks into host slots. Not a catalog
+   * "surface" — the host's AppSurface derivation excludes it on purpose.
+   */
+  Ui: "ui"
 };
 function capability(kind, impl) {
   return { kind, impl };
@@ -489,6 +635,9 @@ function analyticsCapability(impl) {
 function invoicingCapability(impl) {
   return { kind: CapabilityKind.Invoicing, impl };
 }
+function uiCapability(impl) {
+  return { kind: CapabilityKind.Ui, impl };
+}
 var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
 function definePlugin(factory) {
   Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
@@ -501,40 +650,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.7";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -551,12 +668,15 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
 }
 export {
   ANALYTICS_PLUGIN_TOKEN,
+  AUTHOR_HANDLE_RE,
   ActionVariant,
   AnalyticsFeature,
   BlockType,
   CapabilityKind,
   CodFeeType,
   ConfigScope,
+  ContentActionVariant,
+  ContentBlockType,
   FieldType,
   FieldVariant,
   GatewayEnvironment,
@@ -567,7 +687,6 @@ export {
   LayoutMode,
   MessageVariant,
   PAYMENT_PLUGIN_TOKEN,
-  PluginType,
   RepeaterSource,
   SDK_VERSION,
   SHIPPING_PLUGIN_TOKEN,
@@ -592,5 +711,8 @@ export {
   paymentCapability,
   shippingCapability,
   suppliersCapability,
-  validateSetupLayout
+  uiCapability,
+  validatePluginAuthor,
+  validateSetupLayout,
+  validateUiContributions
 };

package/dist/testing/index.d.mts

@@ -0,0 +1,54 @@
+import { _ as HostApi, a0 as HttpRequest, R as DomainEventName, u as Capability, Q as DomainEventHandler, a1 as HttpResponse, N as DispatchContext } from '../host-api-yX49e7zE.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 { _ as HostApi, a0 as HttpRequest, R as DomainEventName, u as Capability, Q as DomainEventHandler, a1 as HttpResponse, N as DispatchContext } from '../host-api-yX49e7zE.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 };