@vivoa/plugin-sdk 0.5.0

package/dist/index.mjs

@@ -0,0 +1,526 @@
+// src/tokens.ts
+var PAYMENT_PLUGIN_TOKEN = "PAYMENT_PLUGINS";
+var SHIPPING_PLUGIN_TOKEN = "SHIPPING_PLUGINS";
+
+// src/plugin.ts
+var PluginType = /* @__PURE__ */ ((PluginType2) => {
+  PluginType2["Payment"] = "payment";
+  PluginType2["Shipping"] = "shipping";
+  PluginType2["Analytics"] = "analytics";
+  PluginType2["Generic"] = "generic";
+  return PluginType2;
+})(PluginType || {});
+var MessageVariant = /* @__PURE__ */ ((MessageVariant2) => {
+  MessageVariant2["Info"] = "info";
+  MessageVariant2["Warning"] = "warning";
+  MessageVariant2["Success"] = "success";
+  MessageVariant2["Danger"] = "danger";
+  return MessageVariant2;
+})(MessageVariant || {});
+function isConfigurablePlugin(plugin) {
+  return typeof plugin === "object" && plugin !== null && "loadConfig" in plugin && typeof plugin.loadConfig === "function";
+}
+
+// src/config.ts
+var FieldType = /* @__PURE__ */ ((FieldType2) => {
+  FieldType2["String"] = "string";
+  FieldType2["Password"] = "password";
+  FieldType2["Url"] = "url";
+  FieldType2["Number"] = "number";
+  FieldType2["Boolean"] = "boolean";
+  FieldType2["Select"] = "select";
+  return FieldType2;
+})(FieldType || {});
+var ConfigScope = /* @__PURE__ */ ((ConfigScope2) => {
+  ConfigScope2["Global"] = "global";
+  ConfigScope2["Country"] = "country";
+  return ConfigScope2;
+})(ConfigScope || {});
+
+// src/config-schema.ts
+import {
+  string,
+  number,
+  boolean,
+  optional,
+  enums,
+  type as structType,
+  validate
+} from "superstruct";
+function field(def) {
+  return { required: true, ...def };
+}
+function normalizeDependsOn(dep) {
+  if (!dep) return void 0;
+  return {
+    field: dep.field,
+    value: Array.isArray(dep.value) ? dep.value : [dep.value]
+  };
+}
+function buildStructForField(def) {
+  let base;
+  if (def.options) {
+    base = enums(def.options.map((o) => o.value));
+  } else if (def.type === "boolean" /* Boolean */) {
+    base = boolean();
+  } else if (def.type === "number" /* Number */) {
+    base = number();
+  } else {
+    base = string();
+  }
+  return def.required ? base : optional(base);
+}
+function createPluginConfig(fields) {
+  const shape = {};
+  const configFields = [];
+  for (const [key, def] of Object.entries(fields)) {
+    shape[key] = buildStructForField(def);
+    configFields.push({
+      key,
+      label: def.label,
+      type: def.type,
+      required: def.required ?? true,
+      scopedTo: def.scopedTo,
+      dependsOn: normalizeDependsOn(def.dependsOn),
+      placeholder: def.placeholder,
+      description: def.description,
+      options: def.options,
+      internal: def.internal,
+      group: def.group
+    });
+  }
+  const schema = structType(shape);
+  return {
+    configFields,
+    validate: (data) => {
+      const [error, result] = validate(data, schema);
+      if (error) {
+        const messages = error.failures().map((f) => {
+          const path = f.path.join(".");
+          return path ? `${path}: ${f.message}` : f.message;
+        });
+        return { success: false, errors: messages };
+      }
+      return { success: true, data: result };
+    }
+  };
+}
+
+// src/payment.ts
+var TransactionStatus = /* @__PURE__ */ ((TransactionStatus2) => {
+  TransactionStatus2["Pending"] = "Pending";
+  TransactionStatus2["PendingRedirect"] = "Pending_Redirect";
+  TransactionStatus2["Approved"] = "Approved";
+  TransactionStatus2["Declined"] = "Declined";
+  TransactionStatus2["Failed"] = "Failed";
+  TransactionStatus2["Error"] = "Error";
+  return TransactionStatus2;
+})(TransactionStatus || {});
+var GatewayEnvironment = /* @__PURE__ */ ((GatewayEnvironment2) => {
+  GatewayEnvironment2["Sandbox"] = "sandbox";
+  GatewayEnvironment2["Production"] = "production";
+  return GatewayEnvironment2;
+})(GatewayEnvironment || {});
+
+// src/shipping.ts
+var ShippingFeature = /* @__PURE__ */ ((ShippingFeature2) => {
+  ShippingFeature2["Tracking"] = "tracking";
+  ShippingFeature2["Cod"] = "cod";
+  ShippingFeature2["Quotes"] = "quotes";
+  ShippingFeature2["Labels"] = "labels";
+  return ShippingFeature2;
+})(ShippingFeature || {});
+var CodFeeType = /* @__PURE__ */ ((CodFeeType2) => {
+  CodFeeType2["Percentage"] = "percentage";
+  CodFeeType2["Fixed"] = "fixed";
+  return CodFeeType2;
+})(CodFeeType || {});
+
+// src/setup-layout.ts
+import {
+  array,
+  boolean as boolean2,
+  enums as enums2,
+  lazy,
+  literal,
+  number as number2,
+  object,
+  optional as optional2,
+  string as string2,
+  union,
+  unknown,
+  validate as validate2
+} from "superstruct";
+var FieldVariant = /* @__PURE__ */ ((FieldVariant2) => {
+  FieldVariant2["Text"] = "text";
+  FieldVariant2["Secret"] = "secret";
+  FieldVariant2["Url"] = "url";
+  FieldVariant2["Number"] = "number";
+  FieldVariant2["Select"] = "select";
+  FieldVariant2["Textarea"] = "textarea";
+  FieldVariant2["Segmented"] = "segmented";
+  return FieldVariant2;
+})(FieldVariant || {});
+var ActionVariant = /* @__PURE__ */ ((ActionVariant2) => {
+  ActionVariant2["Primary"] = "primary";
+  ActionVariant2["Secondary"] = "secondary";
+  ActionVariant2["Danger"] = "danger";
+  return ActionVariant2;
+})(ActionVariant || {});
+var RepeaterSource = /* @__PURE__ */ ((RepeaterSource2) => {
+  RepeaterSource2["SupportedCountries"] = "supportedCountries";
+  return RepeaterSource2;
+})(RepeaterSource || {});
+var LayoutMode = /* @__PURE__ */ ((LayoutMode2) => {
+  LayoutMode2["Wizard"] = "wizard";
+  LayoutMode2["Stacked"] = "stacked";
+  LayoutMode2["Tabs"] = "tabs";
+  LayoutMode2["Sections"] = "sections";
+  return LayoutMode2;
+})(LayoutMode || {});
+var BlockType = /* @__PURE__ */ ((BlockType2) => {
+  BlockType2["Field"] = "field";
+  BlockType2["Group"] = "group";
+  BlockType2["Toggle"] = "toggle";
+  BlockType2["Action"] = "action";
+  BlockType2["Callout"] = "callout";
+  BlockType2["Markdown"] = "markdown";
+  BlockType2["Divider"] = "divider";
+  BlockType2["Conditional"] = "conditional";
+  BlockType2["Repeater"] = "repeater";
+  BlockType2["Card"] = "card";
+  BlockType2["Banner"] = "banner";
+  BlockType2["CopyField"] = "copyField";
+  BlockType2["InlineRow"] = "inlineRow";
+  BlockType2["Tabs"] = "tabs";
+  BlockType2["Accordion"] = "accordion";
+  BlockType2["KeyValue"] = "keyValue";
+  return BlockType2;
+})(BlockType || {});
+var StepStatusFrom = /* @__PURE__ */ ((StepStatusFrom2) => {
+  StepStatusFrom2["Fields"] = "fields";
+  StepStatusFrom2["Action"] = "action";
+  return StepStatusFrom2;
+})(StepStatusFrom || {});
+var sFieldVariant = enums2(Object.values(FieldVariant));
+var sActionVariant = enums2(Object.values(ActionVariant));
+var sRepeaterSource = enums2(Object.values(RepeaterSource));
+var sMessageVariant = enums2(Object.values(MessageVariant));
+var sSpan = optional2(number2());
+var sFieldBlock = object({
+  type: literal("field" /* Field */),
+  key: string2(),
+  variant: optional2(sFieldVariant),
+  labelOverride: optional2(string2()),
+  optionsFrom: optional2(string2()),
+  span: sSpan
+});
+var sGroupBlock = object({
+  type: literal("group" /* Group */),
+  title: string2(),
+  description: optional2(string2()),
+  fields: array(string2()),
+  collapsible: optional2(boolean2()),
+  defaultOpen: optional2(boolean2()),
+  span: sSpan
+});
+var sToggleBlock = object({
+  type: literal("toggle" /* Toggle */),
+  key: string2(),
+  label: string2(),
+  description: optional2(string2()),
+  span: sSpan
+});
+var sActionBlock = object({
+  type: literal("action" /* Action */),
+  id: string2(),
+  label: string2(),
+  variant: optional2(sActionVariant),
+  resultSlot: optional2(string2()),
+  span: sSpan
+});
+var sCalloutBlock = object({
+  type: literal("callout" /* Callout */),
+  variant: sMessageVariant,
+  text: string2(),
+  slot: optional2(string2()),
+  span: sSpan
+});
+var sMarkdownBlock = object({
+  type: literal("markdown" /* Markdown */),
+  content: string2(),
+  span: sSpan
+});
+var sDividerBlock = object({ type: literal("divider" /* Divider */), span: sSpan });
+var sConditionalBlock = object({
+  type: literal("conditional" /* Conditional */),
+  when: object({ key: string2(), equals: unknown() }),
+  blocks: array(lazy(() => sBlock)),
+  span: sSpan
+});
+var sRepeaterBlock = object({
+  type: literal("repeater" /* Repeater */),
+  source: sRepeaterSource,
+  blocks: array(lazy(() => sBlock)),
+  span: sSpan
+});
+var sCardBlock = object({
+  type: literal("card" /* Card */),
+  title: optional2(string2()),
+  description: optional2(string2()),
+  blocks: array(lazy(() => sBlock)),
+  span: sSpan
+});
+var sBannerBlock = object({
+  type: literal("banner" /* Banner */),
+  variant: sMessageVariant,
+  title: optional2(string2()),
+  text: string2(),
+  span: sSpan
+});
+var sCopyFieldBlock = object({
+  type: literal("copyField" /* CopyField */),
+  label: string2(),
+  value: optional2(string2()),
+  computedKey: optional2(string2()),
+  fieldKey: optional2(string2()),
+  span: sSpan
+});
+var sInlineRowBlock = object({
+  type: literal("inlineRow" /* InlineRow */),
+  blocks: array(lazy(() => sBlock)),
+  span: sSpan
+});
+var sTabsBlock = object({
+  type: literal("tabs" /* Tabs */),
+  tabs: array(
+    object({
+      id: string2(),
+      label: string2(),
+      blocks: array(lazy(() => sBlock))
+    })
+  ),
+  span: sSpan
+});
+var sAccordionBlock = object({
+  type: literal("accordion" /* Accordion */),
+  sections: array(
+    object({
+      id: string2(),
+      title: string2(),
+      defaultOpen: optional2(boolean2()),
+      blocks: array(lazy(() => sBlock))
+    })
+  ),
+  span: sSpan
+});
+var sKeyValueBlock = object({
+  type: literal("keyValue" /* KeyValue */),
+  rows: array(
+    object({
+      label: string2(),
+      value: optional2(string2()),
+      computedKey: optional2(string2())
+    })
+  ),
+  span: sSpan
+});
+var sBlock = union([
+  sFieldBlock,
+  sGroupBlock,
+  sToggleBlock,
+  sActionBlock,
+  sCalloutBlock,
+  sMarkdownBlock,
+  sDividerBlock,
+  sConditionalBlock,
+  sRepeaterBlock,
+  sCardBlock,
+  sBannerBlock,
+  sCopyFieldBlock,
+  sInlineRowBlock,
+  sTabsBlock,
+  sAccordionBlock,
+  sKeyValueBlock
+]);
+var sStep = object({
+  id: string2(),
+  title: string2(),
+  intro: optional2(string2()),
+  blocks: array(sBlock),
+  repeatFor: optional2(sRepeaterSource),
+  status: optional2(
+    union([
+      object({ from: literal("fields" /* Fields */) }),
+      object({ from: literal("action" /* Action */), actionId: string2() })
+    ])
+  )
+});
+var sAction = object({
+  id: string2(),
+  label: optional2(string2()),
+  perCountry: optional2(boolean2())
+});
+var sSetupLayout = object({
+  customScreen: optional2(string2()),
+  mode: optional2(enums2(Object.values(LayoutMode))),
+  intro: optional2(string2()),
+  steps: array(sStep),
+  actions: optional2(array(sAction))
+});
+function validateSetupLayout(input) {
+  const [error, result] = validate2(input, sSetupLayout);
+  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 };
+}
+function crossValidateSetupLayout(layout, configSchema) {
+  const errors = [];
+  const knownKeys = new Set(configSchema.map((f) => f.key));
+  const knownActions = new Set((layout.actions ?? []).map((a) => a.id));
+  const walk = (blocks, path) => {
+    blocks.forEach((b, i) => {
+      const here = `${path}[${i}]`;
+      if (b.type === "field" /* Field */ && !knownKeys.has(b.key)) {
+        errors.push(`${here}.key: "${b.key}" not in configSchema`);
+      } else if (b.type === "group" /* Group */) {
+        b.fields.forEach((k, j) => {
+          if (!knownKeys.has(k)) {
+            errors.push(`${here}.fields[${j}]: "${k}" not in configSchema`);
+          }
+        });
+      } else if (b.type === "action" /* Action */ && knownActions.size > 0) {
+        if (!knownActions.has(b.id)) {
+          errors.push(`${here}.id: action "${b.id}" not declared`);
+        }
+      } else if (b.type === "conditional" /* Conditional */ || b.type === "repeater" /* Repeater */ || b.type === "card" /* Card */ || b.type === "inlineRow" /* InlineRow */) {
+        walk(b.blocks, `${here}.blocks`);
+      } else if (b.type === "tabs" /* Tabs */) {
+        b.tabs.forEach((t, j) => walk(t.blocks, `${here}.tabs[${j}].blocks`));
+      } else if (b.type === "accordion" /* Accordion */) {
+        b.sections.forEach(
+          (s, j) => walk(s.blocks, `${here}.sections[${j}].blocks`)
+        );
+      }
+    });
+  };
+  layout.steps.forEach((s, i) => walk(s.blocks, `steps[${i}].blocks`));
+  return errors;
+}
+
+// src/capability.ts
+var CapabilityKind = {
+  Payment: "payment",
+  Shipping: "shipping",
+  Analytics: "analytics"
+};
+function capability(kind, impl) {
+  return { kind, impl };
+}
+function paymentCapability(impl) {
+  return { kind: CapabilityKind.Payment, impl };
+}
+function shippingCapability(impl) {
+  return { kind: CapabilityKind.Shipping, impl };
+}
+var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
+function definePlugin(factory) {
+  Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
+    value: true,
+    enumerable: false
+  });
+  return factory;
+}
+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.5.0";
+function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  };
+  const p = parse(pluginSdkVersion);
+  const h = parse(hostSdkVersion);
+  if (!p || !h) return false;
+  if (p[0] !== h[0]) return false;
+  if (p[0] === 0) {
+    return p[1] === h[1] && h[2] >= p[2];
+  }
+  return h[1] > p[1] || h[1] === p[1] && h[2] >= p[2];
+}
+export {
+  ActionVariant,
+  BlockType,
+  CapabilityKind,
+  CodFeeType,
+  ConfigScope,
+  FieldType,
+  FieldVariant,
+  GatewayEnvironment,
+  LayoutMode,
+  MessageVariant,
+  PAYMENT_PLUGIN_TOKEN,
+  PluginType,
+  RepeaterSource,
+  SDK_VERSION,
+  SHIPPING_PLUGIN_TOKEN,
+  ShippingFeature,
+  StepStatusFrom,
+  TransactionStatus,
+  capability,
+  checkPermissions,
+  createPluginConfig,
+  crossValidateSetupLayout,
+  definePlugin,
+  field,
+  isConfigurablePlugin,
+  isPermissionGranted,
+  isPluginFactory,
+  isSdkCompatible,
+  parsePermission,
+  paymentCapability,
+  shippingCapability,
+  validateSetupLayout
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@vivoa/plugin-sdk",
+  "version": "0.5.0",
+  "description": "Public contracts for Vivoa plugins (types, DI tokens, config + setup-layout validators)",
+  "license": "MIT",
+  "author": "Vivoa",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VivoaPlatform/vivoa-plugin-sdk.git"
+  },
+  "keywords": [
+    "vivoa",
+    "plugin",
+    "sdk",
+    "ecommerce",
+    "payment",
+    "shipping"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "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",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build"
+  },
+  "dependencies": {
+    "superstruct": "^2.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}