@vivoa/plugin-sdk 0.6.3 → 0.6.6

package/README.md

@@ -7,8 +7,8 @@ A plugin author depends on this package; the Vivoa host re-exports it as its
 single source of truth for plugin shapes.
 
 > **Building a plugin?** Read [`AUTHORING.md`](./AUTHORING.md) — the complete,
-> AI-legible guide (anatomy, `IPaymentPlugin`/`IShippingPlugin`, config, setup
-> layout, permissions, build/publish, and the host landmines to avoid).
+> AI-legible guide (anatomy, capabilities, config, setup layout, permissions,
+> build/publish, and the host landmines to avoid).
 
 ## Install
 
@@ -16,41 +16,177 @@ single source of truth for plugin shapes.
 npm install @vivoa/plugin-sdk
 ```
 
-## What's inside
+## Capabilities
 
-| Module           | Exports                                                                 |
-| ---------------- | ----------------------------------------------------------------------- |
-| `types`          | `IPlugin`, `IPaymentPlugin`, `IShippingPlugin`, payment/shipping models, DI tokens |
-| `manifest`       | `PluginManifest`                                                        |
-| `config-schema`  | `createPluginConfig`, `field` — declarative config + superstruct validation |
-| `setup-layout`   | `SetupLayout` types, `validateSetupLayout`, `crossValidateSetupLayout`  |
+A plugin is a **factory function** `(host: HostApi) => Plugin` that declares
+capabilities instead of extending a NestJS module. The host routes by
+`CapabilityKind` string — adding a new kind never touches host-core code.
 
-All exported from the package root:
+| `CapabilityKind` | Interface | Helper |
+|---|---|---|
+| `payment` | `IPaymentPlugin` | `paymentCapability(impl)` |
+| `shipping` | `IShippingPlugin` | `shippingCapability(impl)` |
+| `suppliers` | `ISuppliersPlugin` | `suppliersCapability(impl)` |
+| `analytics` | `IAnalyticsPlugin` | `analyticsCapability(impl)` |
+| `invoicing` | `IInvoicingPlugin` | `invoicingCapability(impl)` |
+
+A plugin may expose any combination of capabilities (or a custom `kind`).
+
+## Quick start
 
 ```ts
 import {
+  definePlugin,
+  paymentCapability,
   IPaymentPlugin,
   createPluginConfig,
   field,
-  validateSetupLayout,
+} from '@vivoa/plugin-sdk';
+
+const config = createPluginConfig({
+  apiKey: field({ label: 'API Key', type: 'password' }),
+  sandbox: field({ label: 'Sandbox mode', type: 'boolean', required: false }),
+});
+
+const myPaymentPlugin: IPaymentPlugin = {
+  name: 'my-gateway',
+  paymentConfig: {
+    supportedCountries: ['SV'],
+    configSchema: config.configFields,
+    supportedCurrencies: ['USD'],
+  },
+  async createPaymentSession(req, ctx) { /* ... */ },
+  async processPayment(req, ctx)       { /* ... */ },
+  async refundPayment(req, ctx)        { /* ... */ },
+};
+
+export default definePlugin((host) => ({
+  manifest: { code: 'my-gateway', name: 'My Gateway', sdkVersion: SDK_VERSION },
+  capabilities: [paymentCapability(myPaymentPlugin)],
+  onActivate(host) {
+    host.logger.info('my-gateway activated');
+  },
+}));
+```
+
+## Modules
+
+| Module | Key exports |
+|---|---|
+| `plugin` | `IPlugin` |
+| `capability` | `Capability`, `CapabilityKind`, `definePlugin`, `Plugin`, `PluginFactory`, `paymentCapability`, `shippingCapability`, `suppliersCapability`, `analyticsCapability`, `invoicingCapability` |
+| `host-api` | `HostApi`, `Logger`, `HttpClient`, `SecretStore`, `StorageBroker`, `SequenceStore` |
+| `payment` | `IPaymentPlugin`, `PaymentSession`, payment models |
+| `shipping` | `IShippingPlugin`, `ShippingQuote`, shipping models |
+| `suppliers` | `ISuppliersPlugin`, suppliers models |
+| `analytics` | `IAnalyticsPlugin`, `AnalyticsEvent`, `AnalyticsUserData`, `AnalyticsActionSource` |
+| `invoicing` | `IInvoicingPlugin`, `InvoiceRequest`, `InvoiceResult`, `InvoiceStatus`, `InvoiceDocumentType`, `InvoicingFeature` |
+| `manifest` | `PluginManifest` |
+| `config` | `PluginConfigField` |
+| `config-schema` | `createPluginConfig`, `field` — declarative config + superstruct validation |
+| `setup-layout` | `SetupLayout` types, `validateSetupLayout`, `crossValidateSetupLayout` |
+| `permissions` | `Permission`, `parsePermission`, `isPermissionGranted`, `checkPermissions` |
+| `dispatch` | `DispatchContext` |
+| `tokens` | DI tokens (`PAYMENT_PLUGIN_TOKEN`, `SHIPPING_PLUGIN_TOKEN`, ...) |
+| `version` | `SDK_VERSION`, `isSdkCompatible` |
+
+All exported from the package root:
+
+```ts
+import {
+  definePlugin,
+  paymentCapability,
+  invoicingCapability,
+  createPluginConfig,
+  field,
+  SDK_VERSION,
 } from '@vivoa/plugin-sdk';
 ```
 
-## Defining a configurable plugin
+## HostApi
+
+The factory receives a `HostApi` — the plugin's entire window into the host.
+No `@nestjs/*`, no Prisma, no `process.env`.
+
+```ts
+interface HostApi {
+  readonly logger:   Logger;        // structured logging
+  readonly http:     HttpClient;    // outbound HTTP (permission-gated)
+  readonly secrets:  SecretStore;   // per-tenant secrets
+  readonly storage:  StorageBroker; // object storage (presigned)
+  readonly sequence: SequenceStore; // monotonic counters (e.g. audit_no)
+  on(event: string, handler: DomainEventHandler): void;
+  registerCapability<T>(cap: Capability<T>): void;
+}
+```
+
+## DispatchContext
+
+Every interface method receives a `DispatchContext` — the host resolves it per
+call, per tenant. The plugin holds **no per-tenant state**.
+
+```ts
+interface DispatchContext {
+  config:          Record<string, unknown>; // merged global config
+  countryConfig?:  Record<string, unknown>; // country-scoped config
+  countryConfigs?: Record<string, Record<string, unknown>>;
+  countryCode?:    string;
+}
+```
+
+## Invoicing capability (0.6.4)
+
+Country-agnostic electronic-invoicing (DTE / CFDI / …) contract.
+
+```ts
+import {
+  definePlugin,
+  invoicingCapability,
+  IInvoicingPlugin,
+  InvoicingFeature,
+  InvoiceDocumentType,
+  InvoiceStatus,
+} from '@vivoa/plugin-sdk';
+
+const myInvoicingAdapter: IInvoicingPlugin = {
+  name: 'my-dte-adapter',
+  invoicingConfig: {
+    supportedCountries: ['SV'],
+    supportedFeatures: [InvoicingFeature.Issue, InvoicingFeature.Void],
+    supportedDocumentTypes: [
+      InvoiceDocumentType.Invoice,
+      InvoiceDocumentType.CreditInvoice,
+    ],
+    configSchema: [],
+  },
+  async issueInvoice(req, ctx) {
+    // call provider API, return InvoiceResult
+    return { status: InvoiceStatus.Accepted, generationCode: '...' };
+  },
+  async voidInvoice(input, ctx) { /* ... */ },
+};
+
+export default definePlugin((host) => ({
+  manifest: { code: 'my-dte', name: 'My DTE', sdkVersion: SDK_VERSION },
+  capabilities: [invoicingCapability(myInvoicingAdapter)],
+}));
+```
+
+## Declarative config
 
 ```ts
 import { createPluginConfig, field } from '@vivoa/plugin-sdk';
 
 const config = createPluginConfig({
-  apiKey: field({ label: 'API Key', type: 'password' }),
+  apiKey:  field({ label: 'API Key', type: 'password' }),
   sandbox: field({ label: 'Sandbox', type: 'boolean', required: false }),
 });
 
-config.configFields; // -> PluginConfigField[] for the admin UI
-config.validate(input); // -> { success, data | errors }
+config.configFields;           // PluginConfigField[] → rendered by the admin UI
+config.validate(userInput);    // { success, data } | { success: false, errors }
 ```
 
-## Validating a setup layout
+## Setup-layout validation
 
 ```ts
 import { validateSetupLayout, crossValidateSetupLayout } from '@vivoa/plugin-sdk';
@@ -61,10 +197,34 @@ if (!res.success) throw new Error(res.errors.join('\n'));
 const keyErrors = crossValidateSetupLayout(res.data, config.configFields);
 ```
 
+## Permissions
+
+Plugins declare `permissions: string[]` in their manifest. The host enforces
+each mediated port before it executes.
+
+```ts
+// domain.action  or  domain.action:resource
+const required = parsePermission('http.outbound:api.provider.com');
+const ok = isPermissionGranted(required, grantedList);
+```
+
 ## Versioning
 
-Semver. Breaking changes to any exported type or validator bump the major.
-Plugins should pin a caret range (`^0.1.0`).
+Semver. `SDK_VERSION` constant mirrors `package.json`. Use `isSdkCompatible` in
+the host to check plugin compatibility.
+
+**0.x convention:** the minor acts as the breaking boundary (matching
+`^0.x` semantics). Additive changes ship as a **PATCH** to keep 0.x plugins
+compatible across the same minor.
+
+```ts
+import { SDK_VERSION, isSdkCompatible } from '@vivoa/plugin-sdk';
+
+// in the host loader:
+if (!isSdkCompatible(plugin.manifest.sdkVersion, SDK_VERSION)) {
+  throw new Error('Incompatible plugin SDK version');
+}
+```
 
 ## License
 

package/dist/chunk-DGJZW46B.mjs

@@ -0,0 +1,37 @@
+// 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 };
+}
+
+export {
+  parsePermission,
+  isPermissionGranted,
+  checkPermissions
+};