@vivoa/plugin-sdk 0.6.2 → 0.6.5

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/index.d.mts

@@ -2,6 +2,7 @@ declare const PAYMENT_PLUGIN_TOKEN: "PAYMENT_PLUGINS";
 declare const SHIPPING_PLUGIN_TOKEN: "SHIPPING_PLUGINS";
 declare const SUPPLIERS_PLUGIN_TOKEN: "SUPPLIERS_PLUGINS";
 declare const ANALYTICS_PLUGIN_TOKEN: "ANALYTICS_PLUGINS";
+declare const INVOICING_PLUGIN_TOKEN: "INVOICING_PLUGINS";
 
 declare enum FieldType {
     String = "string",
@@ -310,6 +311,7 @@ declare enum PluginType {
     Payment = "payment",
     Shipping = "shipping",
     Analytics = "analytics",
+    Invoicing = "invoicing",
     Generic = "generic"
 }
 /** Visual tone for messages, callouts and action results. */
@@ -473,6 +475,13 @@ interface PaymentResult {
     redirectUrl?: string;
     rawResponse?: unknown;
 }
+/**
+ * How the host should render the payment step for this gateway.
+ * - `card-in`         host-owned card form, charged via `processPayment` (default).
+ * - `offsite-redirect` host sends the shopper to `redirectUrl`.
+ * - `embed`           gateway-owned iframe initialised via `createPaymentSession`.
+ */
+type PaymentRenderMode = 'card-in' | 'offsite-redirect' | 'embed';
 interface GatewayStaticConfig {
     code: PaymentGatewayCode;
     displayName: string;
@@ -480,6 +489,53 @@ interface GatewayStaticConfig {
     environment: GatewayEnvironment;
     supportedMethods: string[];
     requiredEnvVars: string[];
+    /**
+     * OPTIONAL render mode. Absent ⇒ host treats the gateway as `'card-in'`.
+     * Back-compat: existing card-in plugins (Wompi/Serfinsa) omit this field.
+     */
+    renderMode?: PaymentRenderMode;
+}
+/**
+ * Cardless payload for creating a gateway-hosted payment session (INV-1).
+ * Used by `embed` / `offsite-redirect` gateways where the host never touches
+ * card data — the shopper enters it inside the gateway's own surface.
+ */
+interface PaymentSessionPayload {
+    /**
+     * Charge amount in DECIMAL major units, 2 decimal places (e.g. `12.34`).
+     * Matches Boxful `@boxful/contracts` `getTwoDecimals` / `toFixed(2)`.
+     */
+    amount: number;
+    currency: string;
+    orderId: string;
+    customer: PaymentCustomer;
+    /** Optional display/reconciliation hints shown on the gateway surface. */
+    orderSummary?: {
+        description?: string;
+        merchant?: string;
+        reference?: string;
+    };
+}
+/**
+ * Everything the host needs to mount a gateway-owned payment iframe.
+ * `sessionToken` is OPAQUE to the host; the amount is sealed server-side by the
+ * gateway, so the host cannot tamper with it.
+ */
+interface EmbedInit {
+    sessionToken: string;
+    iframeUrl: string;
+    allowedOrigins: string[];
+    /** Expiry as epoch SECONDS. Owner TTL guidance: 15 minutes. */
+    expiresAt?: number;
+}
+/**
+ * Result of `createPaymentSession`. `embedInit` is present iff
+ * `renderMode === 'embed'`; `redirectUrl` iff `renderMode === 'offsite-redirect'`.
+ */
+interface PaymentSessionResult {
+    renderMode: PaymentRenderMode;
+    embedInit?: EmbedInit;
+    redirectUrl?: string;
 }
 interface PaymentPluginConfig {
     configSchema: PluginConfigField[];
@@ -505,6 +561,13 @@ interface IPaymentPlugin extends IPlugin {
     queryTransaction?(ref: {
         transactionId: string;
     }, ctx: DispatchContext): Promise<PaymentResult>;
+    /**
+     * Create a gateway-hosted payment session for `embed` / `offsite-redirect`
+     * render modes. OPTIONAL — `card-in` plugins never implement it and charge
+     * via `processPayment` instead. STATELESS: gateway credentials arrive per
+     * call via `ctx.config` (INV-4); no card data is ever passed here (INV-1).
+     */
+    createPaymentSession?(payload: PaymentSessionPayload, ctx: DispatchContext): Promise<PaymentSessionResult>;
 }
 
 declare enum ShippingFeature {
@@ -1012,6 +1075,221 @@ interface IAnalyticsPlugin extends IPlugin {
     isConfigured?(ctx: DispatchContext): boolean;
 }
 
+declare enum InvoicingFeature {
+    /** Emit a fiscal document against the authority. */
+    Issue = "issue",
+    /** Invalidate / annul a previously issued document. */
+    Void = "void",
+    /** Query the current authority status of an issued document. */
+    StatusQuery = "status-query",
+    /** Retrieve the rendered PDF of an issued document. */
+    Pdf = "pdf"
+}
+/**
+ * Generic fiscal document types. The adapter maps each to its national catalog
+ * (e.g. SV MH: Invoice→Factura Consumidor Final "01", CreditInvoice→Comprobante
+ * de Crédito Fiscal "03", ExcludedSubject→Factura Sujeto Excluido "14", ...).
+ */
+declare enum InvoiceDocumentType {
+    /** Final-consumer invoice. */
+    Invoice = "invoice",
+    /** Tax-credit document for registered taxpayers (SV CCF). */
+    CreditInvoice = "credit-invoice",
+    /** Credit note against a prior document. */
+    CreditNote = "credit-note",
+    /** Debit note against a prior document. */
+    DebitNote = "debit-note",
+    /** Document for suppliers not registered as taxpayers (SV Sujeto Excluido). */
+    ExcludedSubject = "excluded-subject",
+    /** Export invoice. */
+    Export = "export"
+}
+/**
+ * Authority status of an issued document. `unknown` is a first-class value for
+ * provider states the adapter does not map — the host treats it as "not yet
+ * resolved" instead of guessing.
+ */
+declare enum InvoiceStatus {
+    /** Submitted, awaiting the authority's acceptance. */
+    Pending = "pending",
+    /** Accepted and sealed by the authority. */
+    Accepted = "accepted",
+    /** Rejected by the authority (see statusDescription for the reason). */
+    Rejected = "rejected",
+    /** Previously accepted, later invalidated/annulled. */
+    Voided = "voided",
+    Unknown = "unknown"
+}
+/**
+ * ISO-4217 money in minor units — mirrors the store's Money VO so the host maps
+ * 1:1 without a currency guess. Kept local so the SDK stays dependency-free.
+ */
+interface InvoiceMoney {
+    amountMinor: number;
+    currency: string;
+}
+/**
+ * A party to the document (issuer or recipient). Fields are generic; the adapter
+ * maps `taxId` to the national identifier it needs (NIT/NRC/DUI in SV, RFC in
+ * MX). Most are optional because a final-consumer invoice needs far less than a
+ * tax-credit document.
+ */
+interface InvoiceParty {
+    /** Legal / trade name of the party. */
+    name: string;
+    /** National tax identifier (SV NIT, MX RFC, ...). */
+    taxId?: string | null;
+    /** Secondary fiscal registry id where the country splits them (SV NRC). */
+    taxRegistryId?: string | null;
+    /** Personal id when the party is a natural person (SV DUI). */
+    personalId?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    address?: string | null;
+    city?: string | null;
+    state?: string | null;
+    country?: string | null;
+    /** Economic-activity code where the authority requires it. */
+    activityCode?: string | null;
+    activityDescription?: string | null;
+}
+/** A tax applied to a line or to the whole document. */
+interface InvoiceTax {
+    /** Generic code (adapter maps to the national tax code, e.g. SV IVA "20"). */
+    code: string;
+    description?: string;
+    /** Rate as a fraction (0.13 for 13% IVA), when the tax is rate-based. */
+    rate?: number;
+    amount: InvoiceMoney;
+}
+/** A single line item of the document. */
+interface InvoiceLine {
+    /** Store product id, for traceability back to the catalog. */
+    productId?: string | null;
+    variantId?: string | null;
+    sku?: string | null;
+    description: string;
+    quantity: number;
+    /** Unit of measure code where the authority requires it. */
+    unitCode?: string | null;
+    unitPrice: InvoiceMoney;
+    /** Line discount, when any. */
+    discount?: InvoiceMoney;
+    /** Line subtotal (quantity * unitPrice - discount), before document taxes. */
+    subtotal: InvoiceMoney;
+    /** Per-line taxes, when the country computes tax at the line level. */
+    taxes?: InvoiceTax[];
+}
+/**
+ * The host builds this from an Order (or a manual admin action) and hands it to
+ * the adapter. Fiscal identifiers are NOT part of the request — the provider
+ * assigns them and returns them on {@link InvoiceResult}.
+ */
+interface InvoiceRequest {
+    /** Store order id, used by the adapter as the idempotency key. */
+    orderId: string;
+    documentType: InvoiceDocumentType;
+    /** ISO-4217 currency of the whole document. */
+    currency: string;
+    /** The seller — defaults to the store's fiscal identity when omitted by host. */
+    issuer?: InvoiceParty;
+    /** The buyer. */
+    recipient: InvoiceParty;
+    lines: InvoiceLine[];
+    /** Document-level taxes (when the country totals tax at the document level). */
+    taxes?: InvoiceTax[];
+    /** Sum of line subtotals before taxes. */
+    subtotal: InvoiceMoney;
+    /** Total taxes applied. */
+    taxTotal?: InvoiceMoney;
+    /** Grand total the customer pays. */
+    total: InvoiceMoney;
+    /** ISO-8601 instant the sale happened. */
+    issuedAt?: string;
+    /** Free-form notes to print on the document. */
+    notes?: string;
+    /** Provider-specific extras the host cannot model generically. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Outcome of an issue / void / query. The fiscal identifiers are provider output
+ * — all optional because a Rejected result may carry none of them. `status`
+ * drives the host's control flow; `rawResponse` is for diagnostics only.
+ */
+interface InvoiceResult {
+    status: InvoiceStatus;
+    /** Authority generation code / UUID (SV "Código de Generación"). */
+    generationCode?: string | null;
+    /** Control number assigned to the document (SV "Número de Control"). */
+    controlNumber?: string | null;
+    /** Authority reception seal confirming validity (SV "Sello de Recepción"). */
+    receptionSeal?: string | null;
+    /** URL to the rendered PDF, when the provider exposes one. */
+    pdfUrl?: string | null;
+    /** URL to the signed JSON artifact, when the provider exposes one. */
+    jsonUrl?: string | null;
+    /** Human-readable authority/provider status, for audit/logging. */
+    statusDescription?: string;
+    /** Untouched provider payload, for diagnostics. Never trusted for control flow. */
+    rawResponse?: Record<string, unknown>;
+}
+/** Input to invalidate a previously issued document. */
+interface VoidInvoiceInput {
+    /** The generation code of the document to invalidate. */
+    generationCode: string;
+    /** Reason for the invalidation, required by most authorities. */
+    reason: string;
+}
+interface InvoicingDefaultConfig {
+    global?: Record<string, unknown>;
+    countries?: Record<string, Record<string, unknown>>;
+}
+interface InvoicingPluginConfig {
+    supportedCountries: string[];
+    supportedFeatures: InvoicingFeature[];
+    supportedDocumentTypes: InvoiceDocumentType[];
+    configSchema: PluginConfigField[];
+    /** GLOBAL + per-country defaults merged under the tenant DB config by the host. */
+    defaultConfig?: InvoicingDefaultConfig;
+}
+interface InvoicingStaticConfig {
+    code: string;
+    displayName: string;
+    description: string;
+    iconUrl?: string;
+    supportedCountries: string[];
+    supportedFeatures: InvoicingFeature[];
+    supportedDocumentTypes: InvoiceDocumentType[];
+    configSchema: PluginConfigField[];
+}
+interface IInvoicingPlugin extends IPlugin {
+    readonly name: string;
+    readonly invoicingConfig: InvoicingPluginConfig;
+    /**
+     * Emit a fiscal document against the authority. Stateless: the tenant's
+     * resolved credentials arrive in `ctx.config` on every call. The adapter uses
+     * `req.orderId` as the idempotency key so a retry never double-issues.
+     */
+    issueInvoice(req: InvoiceRequest, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Invalidate a previously issued document.
+     * @compat Only plugins advertising the {@link InvoicingFeature.Void} feature.
+     */
+    voidInvoice?(input: VoidInvoiceInput, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Query the authority's current status of an issued document.
+     * @compat Only plugins advertising the {@link InvoicingFeature.StatusQuery} feature.
+     */
+    queryStatus?(ref: {
+        generationCode: string;
+    }, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Optional readiness probe. Availability = enabled AND isConfigured.
+     * @compat When omitted, the host assumes the adapter is ready.
+     */
+    isConfigured?(ctx: DispatchContext): boolean;
+}
+
 /** A named unit of behaviour a plugin exposes to the host registry. */
 interface Capability<T = unknown> {
     kind: string;
@@ -1027,6 +1305,7 @@ declare const CapabilityKind: {
     readonly Shipping: "shipping";
     readonly Suppliers: "suppliers";
     readonly Analytics: "analytics";
+    readonly Invoicing: "invoicing";
 };
 type CapabilityKind = (typeof CapabilityKind)[keyof typeof CapabilityKind];
 declare function capability<T>(kind: string, impl: T): Capability<T>;
@@ -1034,6 +1313,7 @@ declare function paymentCapability(impl: IPaymentPlugin): Capability<IPaymentPlu
 declare function shippingCapability(impl: IShippingPlugin): Capability<IShippingPlugin>;
 declare function suppliersCapability(impl: ISuppliersPlugin): Capability<ISuppliersPlugin>;
 declare function analyticsCapability(impl: IAnalyticsPlugin): Capability<IAnalyticsPlugin>;
+declare function invoicingCapability(impl: IInvoicingPlugin): Capability<IInvoicingPlugin>;
 /**
  * A constructed plugin. `capabilities` is the static declaration the host reads
  * up front; `onActivate` runs when the host mounts the plugin for a tenant and
@@ -1171,7 +1451,7 @@ declare function checkPermissions(required: string[], grantedRaw: string[]): Per
  * - MINOR: additive (new optional fields, new tokens) — backwards compatible.
  * - PATCH: docs/fixes with zero shape changes.
  */
-declare const SDK_VERSION = "0.6.2";
+declare const SDK_VERSION = "0.6.5";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -1180,4 +1460,4 @@ declare const SDK_VERSION = "0.6.2";
  */
 declare function isSdkCompatible(pluginSdkVersion: string, hostSdkVersion: string): boolean;
 
-export { ANALYTICS_PLUGIN_TOKEN, type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, type AnalyticsActionSource, type AnalyticsConsent, type AnalyticsEvent, type AnalyticsEventName, AnalyticsFeature, type AnalyticsItem, type AnalyticsMoney, type AnalyticsPluginConfig, type AnalyticsStaticConfig, type AnalyticsUserData, type AnalyticsUtm, type BannerBlock, type Block, type BlockBase, BlockType, type CalloutBlock, type Capability, CapabilityKind, type CardBlock, type CodConfig, type CodFeeConfig, CodFeeType, type ConditionalBlock, type ConditionalEquals, type ConditionalWhen, ConfigScope, type ConfigurablePlugin, type CopyFieldBlock, type CreateShipmentParams, type DispatchContext, type DividerBlock, type DomainEventHandler, type DomainEventName, type FieldBlock, type FieldDefinition, type FieldDependsOn, type FieldMap, type FieldOption, FieldType, FieldVariant, GatewayEnvironment, type GatewayStaticConfig, type GroupBlock, type HostApi, type HttpClient, type HttpRequest, type HttpResponse, type IAnalyticsPlugin, type IPaymentPlugin, type IPlugin, type IShippingPlugin, type ISuppliersPlugin, type InlineRowBlock, type KeyValueBlock, type KeyValueRow, LayoutMode, type Logger, type MarkdownBlock, MessageVariant, PAYMENT_PLUGIN_TOKEN, type PaymentCard, type PaymentCustomer, type PaymentGatewayCode, type PaymentPayload, type PaymentPluginConfig, type PaymentResult, type PaymentVerifyPayload, type Permission, type PermissionCheck, type PlaceSupplierOrderInput, type Plugin, type PluginActionContext, type PluginActionResult, type PluginConfigField, type PluginConfigFieldDependency, type PluginConfigResult, type PluginConfigValidation, type PluginFactory, type PluginManifest, PluginType, type RepeaterBlock, RepeaterSource, SDK_VERSION, SHIPPING_PLUGIN_TOKEN, SUPPLIERS_PLUGIN_TOKEN, type SecretStore, type SelectOption, type SequenceStore, type SetupAction, type SetupLayout, type SetupLayoutValidation, type SetupStep, type ShipmentAddress, type ShipmentParcel, type ShipmentResult, type ShippingDefaultConfig, ShippingFeature, type ShippingPluginConfig, type ShippingQuote, type ShippingQuoteParams, type ShippingStaticConfig, StepStatusFrom, type StepStatusFromAction, type StepStatusFromFields, type StepStatusSource, type StorageBroker, type SupplierCatalogQuery, type SupplierFulfillmentEvent, type SupplierListing, type SupplierListingAttribute, type SupplierListingPage, type SupplierListingVariant, type SupplierMoney, type SupplierOrderAddressLevel, type SupplierOrderCustomer, type SupplierOrderLine, type SupplierOrderResult, type SupplierOrderStatus, type SupplierShipTo, type SupplierStock, type SuppliersDefaultConfig, SuppliersFeature, type SuppliersPluginConfig, type SuppliersStaticConfig, type TabItem, type TabsBlock, type ToggleBlock, type TrackingEvent, TransactionStatus, type WebhookSignatureResult, analyticsCapability, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };
+export { ANALYTICS_PLUGIN_TOKEN, type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, type AnalyticsActionSource, type AnalyticsConsent, type AnalyticsEvent, type AnalyticsEventName, AnalyticsFeature, type AnalyticsItem, type AnalyticsMoney, type AnalyticsPluginConfig, type AnalyticsStaticConfig, type AnalyticsUserData, type AnalyticsUtm, type BannerBlock, type Block, type BlockBase, BlockType, type CalloutBlock, type Capability, CapabilityKind, type CardBlock, type CodConfig, type CodFeeConfig, CodFeeType, type ConditionalBlock, type ConditionalEquals, type ConditionalWhen, ConfigScope, type ConfigurablePlugin, type CopyFieldBlock, type CreateShipmentParams, type DispatchContext, type DividerBlock, type DomainEventHandler, type DomainEventName, type EmbedInit, type FieldBlock, type FieldDefinition, type FieldDependsOn, type FieldMap, type FieldOption, FieldType, FieldVariant, GatewayEnvironment, type GatewayStaticConfig, type GroupBlock, type HostApi, type HttpClient, type HttpRequest, type HttpResponse, type IAnalyticsPlugin, type IInvoicingPlugin, INVOICING_PLUGIN_TOKEN, type IPaymentPlugin, type IPlugin, type IShippingPlugin, type ISuppliersPlugin, type InlineRowBlock, InvoiceDocumentType, type InvoiceLine, type InvoiceMoney, type InvoiceParty, type InvoiceRequest, type InvoiceResult, InvoiceStatus, type InvoiceTax, type InvoicingDefaultConfig, InvoicingFeature, type InvoicingPluginConfig, type InvoicingStaticConfig, type KeyValueBlock, type KeyValueRow, LayoutMode, type Logger, type MarkdownBlock, MessageVariant, PAYMENT_PLUGIN_TOKEN, type PaymentCard, type PaymentCustomer, type PaymentGatewayCode, type PaymentPayload, type PaymentPluginConfig, type PaymentRenderMode, type PaymentResult, type PaymentSessionPayload, type PaymentSessionResult, type PaymentVerifyPayload, type Permission, type PermissionCheck, type PlaceSupplierOrderInput, type Plugin, type PluginActionContext, type PluginActionResult, type PluginConfigField, type PluginConfigFieldDependency, type PluginConfigResult, type PluginConfigValidation, type PluginFactory, type PluginManifest, PluginType, type RepeaterBlock, RepeaterSource, SDK_VERSION, SHIPPING_PLUGIN_TOKEN, SUPPLIERS_PLUGIN_TOKEN, type SecretStore, type SelectOption, type SequenceStore, type SetupAction, type SetupLayout, type SetupLayoutValidation, type SetupStep, type ShipmentAddress, type ShipmentParcel, type ShipmentResult, type ShippingDefaultConfig, ShippingFeature, type ShippingPluginConfig, type ShippingQuote, type ShippingQuoteParams, type ShippingStaticConfig, StepStatusFrom, type StepStatusFromAction, type StepStatusFromFields, type StepStatusSource, type StorageBroker, type SupplierCatalogQuery, type SupplierFulfillmentEvent, type SupplierListing, type SupplierListingAttribute, type SupplierListingPage, type SupplierListingVariant, type SupplierMoney, type SupplierOrderAddressLevel, type SupplierOrderCustomer, type SupplierOrderLine, type SupplierOrderResult, type SupplierOrderStatus, type SupplierShipTo, type SupplierStock, type SuppliersDefaultConfig, SuppliersFeature, type SuppliersPluginConfig, type SuppliersStaticConfig, type TabItem, type TabsBlock, type ToggleBlock, type TrackingEvent, TransactionStatus, type VoidInvoiceInput, type WebhookSignatureResult, analyticsCapability, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, invoicingCapability, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ declare const PAYMENT_PLUGIN_TOKEN: "PAYMENT_PLUGINS";
 declare const SHIPPING_PLUGIN_TOKEN: "SHIPPING_PLUGINS";
 declare const SUPPLIERS_PLUGIN_TOKEN: "SUPPLIERS_PLUGINS";
 declare const ANALYTICS_PLUGIN_TOKEN: "ANALYTICS_PLUGINS";
+declare const INVOICING_PLUGIN_TOKEN: "INVOICING_PLUGINS";
 
 declare enum FieldType {
     String = "string",
@@ -310,6 +311,7 @@ declare enum PluginType {
     Payment = "payment",
     Shipping = "shipping",
     Analytics = "analytics",
+    Invoicing = "invoicing",
     Generic = "generic"
 }
 /** Visual tone for messages, callouts and action results. */
@@ -473,6 +475,13 @@ interface PaymentResult {
     redirectUrl?: string;
     rawResponse?: unknown;
 }
+/**
+ * How the host should render the payment step for this gateway.
+ * - `card-in`         host-owned card form, charged via `processPayment` (default).
+ * - `offsite-redirect` host sends the shopper to `redirectUrl`.
+ * - `embed`           gateway-owned iframe initialised via `createPaymentSession`.
+ */
+type PaymentRenderMode = 'card-in' | 'offsite-redirect' | 'embed';
 interface GatewayStaticConfig {
     code: PaymentGatewayCode;
     displayName: string;
@@ -480,6 +489,53 @@ interface GatewayStaticConfig {
     environment: GatewayEnvironment;
     supportedMethods: string[];
     requiredEnvVars: string[];
+    /**
+     * OPTIONAL render mode. Absent ⇒ host treats the gateway as `'card-in'`.
+     * Back-compat: existing card-in plugins (Wompi/Serfinsa) omit this field.
+     */
+    renderMode?: PaymentRenderMode;
+}
+/**
+ * Cardless payload for creating a gateway-hosted payment session (INV-1).
+ * Used by `embed` / `offsite-redirect` gateways where the host never touches
+ * card data — the shopper enters it inside the gateway's own surface.
+ */
+interface PaymentSessionPayload {
+    /**
+     * Charge amount in DECIMAL major units, 2 decimal places (e.g. `12.34`).
+     * Matches Boxful `@boxful/contracts` `getTwoDecimals` / `toFixed(2)`.
+     */
+    amount: number;
+    currency: string;
+    orderId: string;
+    customer: PaymentCustomer;
+    /** Optional display/reconciliation hints shown on the gateway surface. */
+    orderSummary?: {
+        description?: string;
+        merchant?: string;
+        reference?: string;
+    };
+}
+/**
+ * Everything the host needs to mount a gateway-owned payment iframe.
+ * `sessionToken` is OPAQUE to the host; the amount is sealed server-side by the
+ * gateway, so the host cannot tamper with it.
+ */
+interface EmbedInit {
+    sessionToken: string;
+    iframeUrl: string;
+    allowedOrigins: string[];
+    /** Expiry as epoch SECONDS. Owner TTL guidance: 15 minutes. */
+    expiresAt?: number;
+}
+/**
+ * Result of `createPaymentSession`. `embedInit` is present iff
+ * `renderMode === 'embed'`; `redirectUrl` iff `renderMode === 'offsite-redirect'`.
+ */
+interface PaymentSessionResult {
+    renderMode: PaymentRenderMode;
+    embedInit?: EmbedInit;
+    redirectUrl?: string;
 }
 interface PaymentPluginConfig {
     configSchema: PluginConfigField[];
@@ -505,6 +561,13 @@ interface IPaymentPlugin extends IPlugin {
     queryTransaction?(ref: {
         transactionId: string;
     }, ctx: DispatchContext): Promise<PaymentResult>;
+    /**
+     * Create a gateway-hosted payment session for `embed` / `offsite-redirect`
+     * render modes. OPTIONAL — `card-in` plugins never implement it and charge
+     * via `processPayment` instead. STATELESS: gateway credentials arrive per
+     * call via `ctx.config` (INV-4); no card data is ever passed here (INV-1).
+     */
+    createPaymentSession?(payload: PaymentSessionPayload, ctx: DispatchContext): Promise<PaymentSessionResult>;
 }
 
 declare enum ShippingFeature {
@@ -1012,6 +1075,221 @@ interface IAnalyticsPlugin extends IPlugin {
     isConfigured?(ctx: DispatchContext): boolean;
 }
 
+declare enum InvoicingFeature {
+    /** Emit a fiscal document against the authority. */
+    Issue = "issue",
+    /** Invalidate / annul a previously issued document. */
+    Void = "void",
+    /** Query the current authority status of an issued document. */
+    StatusQuery = "status-query",
+    /** Retrieve the rendered PDF of an issued document. */
+    Pdf = "pdf"
+}
+/**
+ * Generic fiscal document types. The adapter maps each to its national catalog
+ * (e.g. SV MH: Invoice→Factura Consumidor Final "01", CreditInvoice→Comprobante
+ * de Crédito Fiscal "03", ExcludedSubject→Factura Sujeto Excluido "14", ...).
+ */
+declare enum InvoiceDocumentType {
+    /** Final-consumer invoice. */
+    Invoice = "invoice",
+    /** Tax-credit document for registered taxpayers (SV CCF). */
+    CreditInvoice = "credit-invoice",
+    /** Credit note against a prior document. */
+    CreditNote = "credit-note",
+    /** Debit note against a prior document. */
+    DebitNote = "debit-note",
+    /** Document for suppliers not registered as taxpayers (SV Sujeto Excluido). */
+    ExcludedSubject = "excluded-subject",
+    /** Export invoice. */
+    Export = "export"
+}
+/**
+ * Authority status of an issued document. `unknown` is a first-class value for
+ * provider states the adapter does not map — the host treats it as "not yet
+ * resolved" instead of guessing.
+ */
+declare enum InvoiceStatus {
+    /** Submitted, awaiting the authority's acceptance. */
+    Pending = "pending",
+    /** Accepted and sealed by the authority. */
+    Accepted = "accepted",
+    /** Rejected by the authority (see statusDescription for the reason). */
+    Rejected = "rejected",
+    /** Previously accepted, later invalidated/annulled. */
+    Voided = "voided",
+    Unknown = "unknown"
+}
+/**
+ * ISO-4217 money in minor units — mirrors the store's Money VO so the host maps
+ * 1:1 without a currency guess. Kept local so the SDK stays dependency-free.
+ */
+interface InvoiceMoney {
+    amountMinor: number;
+    currency: string;
+}
+/**
+ * A party to the document (issuer or recipient). Fields are generic; the adapter
+ * maps `taxId` to the national identifier it needs (NIT/NRC/DUI in SV, RFC in
+ * MX). Most are optional because a final-consumer invoice needs far less than a
+ * tax-credit document.
+ */
+interface InvoiceParty {
+    /** Legal / trade name of the party. */
+    name: string;
+    /** National tax identifier (SV NIT, MX RFC, ...). */
+    taxId?: string | null;
+    /** Secondary fiscal registry id where the country splits them (SV NRC). */
+    taxRegistryId?: string | null;
+    /** Personal id when the party is a natural person (SV DUI). */
+    personalId?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    address?: string | null;
+    city?: string | null;
+    state?: string | null;
+    country?: string | null;
+    /** Economic-activity code where the authority requires it. */
+    activityCode?: string | null;
+    activityDescription?: string | null;
+}
+/** A tax applied to a line or to the whole document. */
+interface InvoiceTax {
+    /** Generic code (adapter maps to the national tax code, e.g. SV IVA "20"). */
+    code: string;
+    description?: string;
+    /** Rate as a fraction (0.13 for 13% IVA), when the tax is rate-based. */
+    rate?: number;
+    amount: InvoiceMoney;
+}
+/** A single line item of the document. */
+interface InvoiceLine {
+    /** Store product id, for traceability back to the catalog. */
+    productId?: string | null;
+    variantId?: string | null;
+    sku?: string | null;
+    description: string;
+    quantity: number;
+    /** Unit of measure code where the authority requires it. */
+    unitCode?: string | null;
+    unitPrice: InvoiceMoney;
+    /** Line discount, when any. */
+    discount?: InvoiceMoney;
+    /** Line subtotal (quantity * unitPrice - discount), before document taxes. */
+    subtotal: InvoiceMoney;
+    /** Per-line taxes, when the country computes tax at the line level. */
+    taxes?: InvoiceTax[];
+}
+/**
+ * The host builds this from an Order (or a manual admin action) and hands it to
+ * the adapter. Fiscal identifiers are NOT part of the request — the provider
+ * assigns them and returns them on {@link InvoiceResult}.
+ */
+interface InvoiceRequest {
+    /** Store order id, used by the adapter as the idempotency key. */
+    orderId: string;
+    documentType: InvoiceDocumentType;
+    /** ISO-4217 currency of the whole document. */
+    currency: string;
+    /** The seller — defaults to the store's fiscal identity when omitted by host. */
+    issuer?: InvoiceParty;
+    /** The buyer. */
+    recipient: InvoiceParty;
+    lines: InvoiceLine[];
+    /** Document-level taxes (when the country totals tax at the document level). */
+    taxes?: InvoiceTax[];
+    /** Sum of line subtotals before taxes. */
+    subtotal: InvoiceMoney;
+    /** Total taxes applied. */
+    taxTotal?: InvoiceMoney;
+    /** Grand total the customer pays. */
+    total: InvoiceMoney;
+    /** ISO-8601 instant the sale happened. */
+    issuedAt?: string;
+    /** Free-form notes to print on the document. */
+    notes?: string;
+    /** Provider-specific extras the host cannot model generically. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Outcome of an issue / void / query. The fiscal identifiers are provider output
+ * — all optional because a Rejected result may carry none of them. `status`
+ * drives the host's control flow; `rawResponse` is for diagnostics only.
+ */
+interface InvoiceResult {
+    status: InvoiceStatus;
+    /** Authority generation code / UUID (SV "Código de Generación"). */
+    generationCode?: string | null;
+    /** Control number assigned to the document (SV "Número de Control"). */
+    controlNumber?: string | null;
+    /** Authority reception seal confirming validity (SV "Sello de Recepción"). */
+    receptionSeal?: string | null;
+    /** URL to the rendered PDF, when the provider exposes one. */
+    pdfUrl?: string | null;
+    /** URL to the signed JSON artifact, when the provider exposes one. */
+    jsonUrl?: string | null;
+    /** Human-readable authority/provider status, for audit/logging. */
+    statusDescription?: string;
+    /** Untouched provider payload, for diagnostics. Never trusted for control flow. */
+    rawResponse?: Record<string, unknown>;
+}
+/** Input to invalidate a previously issued document. */
+interface VoidInvoiceInput {
+    /** The generation code of the document to invalidate. */
+    generationCode: string;
+    /** Reason for the invalidation, required by most authorities. */
+    reason: string;
+}
+interface InvoicingDefaultConfig {
+    global?: Record<string, unknown>;
+    countries?: Record<string, Record<string, unknown>>;
+}
+interface InvoicingPluginConfig {
+    supportedCountries: string[];
+    supportedFeatures: InvoicingFeature[];
+    supportedDocumentTypes: InvoiceDocumentType[];
+    configSchema: PluginConfigField[];
+    /** GLOBAL + per-country defaults merged under the tenant DB config by the host. */
+    defaultConfig?: InvoicingDefaultConfig;
+}
+interface InvoicingStaticConfig {
+    code: string;
+    displayName: string;
+    description: string;
+    iconUrl?: string;
+    supportedCountries: string[];
+    supportedFeatures: InvoicingFeature[];
+    supportedDocumentTypes: InvoiceDocumentType[];
+    configSchema: PluginConfigField[];
+}
+interface IInvoicingPlugin extends IPlugin {
+    readonly name: string;
+    readonly invoicingConfig: InvoicingPluginConfig;
+    /**
+     * Emit a fiscal document against the authority. Stateless: the tenant's
+     * resolved credentials arrive in `ctx.config` on every call. The adapter uses
+     * `req.orderId` as the idempotency key so a retry never double-issues.
+     */
+    issueInvoice(req: InvoiceRequest, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Invalidate a previously issued document.
+     * @compat Only plugins advertising the {@link InvoicingFeature.Void} feature.
+     */
+    voidInvoice?(input: VoidInvoiceInput, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Query the authority's current status of an issued document.
+     * @compat Only plugins advertising the {@link InvoicingFeature.StatusQuery} feature.
+     */
+    queryStatus?(ref: {
+        generationCode: string;
+    }, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Optional readiness probe. Availability = enabled AND isConfigured.
+     * @compat When omitted, the host assumes the adapter is ready.
+     */
+    isConfigured?(ctx: DispatchContext): boolean;
+}
+
 /** A named unit of behaviour a plugin exposes to the host registry. */
 interface Capability<T = unknown> {
     kind: string;
@@ -1027,6 +1305,7 @@ declare const CapabilityKind: {
     readonly Shipping: "shipping";
     readonly Suppliers: "suppliers";
     readonly Analytics: "analytics";
+    readonly Invoicing: "invoicing";
 };
 type CapabilityKind = (typeof CapabilityKind)[keyof typeof CapabilityKind];
 declare function capability<T>(kind: string, impl: T): Capability<T>;
@@ -1034,6 +1313,7 @@ declare function paymentCapability(impl: IPaymentPlugin): Capability<IPaymentPlu
 declare function shippingCapability(impl: IShippingPlugin): Capability<IShippingPlugin>;
 declare function suppliersCapability(impl: ISuppliersPlugin): Capability<ISuppliersPlugin>;
 declare function analyticsCapability(impl: IAnalyticsPlugin): Capability<IAnalyticsPlugin>;
+declare function invoicingCapability(impl: IInvoicingPlugin): Capability<IInvoicingPlugin>;
 /**
  * A constructed plugin. `capabilities` is the static declaration the host reads
  * up front; `onActivate` runs when the host mounts the plugin for a tenant and
@@ -1171,7 +1451,7 @@ declare function checkPermissions(required: string[], grantedRaw: string[]): Per
  * - MINOR: additive (new optional fields, new tokens) — backwards compatible.
  * - PATCH: docs/fixes with zero shape changes.
  */
-declare const SDK_VERSION = "0.6.2";
+declare const SDK_VERSION = "0.6.5";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -1180,4 +1460,4 @@ declare const SDK_VERSION = "0.6.2";
  */
 declare function isSdkCompatible(pluginSdkVersion: string, hostSdkVersion: string): boolean;
 
-export { ANALYTICS_PLUGIN_TOKEN, type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, type AnalyticsActionSource, type AnalyticsConsent, type AnalyticsEvent, type AnalyticsEventName, AnalyticsFeature, type AnalyticsItem, type AnalyticsMoney, type AnalyticsPluginConfig, type AnalyticsStaticConfig, type AnalyticsUserData, type AnalyticsUtm, type BannerBlock, type Block, type BlockBase, BlockType, type CalloutBlock, type Capability, CapabilityKind, type CardBlock, type CodConfig, type CodFeeConfig, CodFeeType, type ConditionalBlock, type ConditionalEquals, type ConditionalWhen, ConfigScope, type ConfigurablePlugin, type CopyFieldBlock, type CreateShipmentParams, type DispatchContext, type DividerBlock, type DomainEventHandler, type DomainEventName, type FieldBlock, type FieldDefinition, type FieldDependsOn, type FieldMap, type FieldOption, FieldType, FieldVariant, GatewayEnvironment, type GatewayStaticConfig, type GroupBlock, type HostApi, type HttpClient, type HttpRequest, type HttpResponse, type IAnalyticsPlugin, type IPaymentPlugin, type IPlugin, type IShippingPlugin, type ISuppliersPlugin, type InlineRowBlock, type KeyValueBlock, type KeyValueRow, LayoutMode, type Logger, type MarkdownBlock, MessageVariant, PAYMENT_PLUGIN_TOKEN, type PaymentCard, type PaymentCustomer, type PaymentGatewayCode, type PaymentPayload, type PaymentPluginConfig, type PaymentResult, type PaymentVerifyPayload, type Permission, type PermissionCheck, type PlaceSupplierOrderInput, type Plugin, type PluginActionContext, type PluginActionResult, type PluginConfigField, type PluginConfigFieldDependency, type PluginConfigResult, type PluginConfigValidation, type PluginFactory, type PluginManifest, PluginType, type RepeaterBlock, RepeaterSource, SDK_VERSION, SHIPPING_PLUGIN_TOKEN, SUPPLIERS_PLUGIN_TOKEN, type SecretStore, type SelectOption, type SequenceStore, type SetupAction, type SetupLayout, type SetupLayoutValidation, type SetupStep, type ShipmentAddress, type ShipmentParcel, type ShipmentResult, type ShippingDefaultConfig, ShippingFeature, type ShippingPluginConfig, type ShippingQuote, type ShippingQuoteParams, type ShippingStaticConfig, StepStatusFrom, type StepStatusFromAction, type StepStatusFromFields, type StepStatusSource, type StorageBroker, type SupplierCatalogQuery, type SupplierFulfillmentEvent, type SupplierListing, type SupplierListingAttribute, type SupplierListingPage, type SupplierListingVariant, type SupplierMoney, type SupplierOrderAddressLevel, type SupplierOrderCustomer, type SupplierOrderLine, type SupplierOrderResult, type SupplierOrderStatus, type SupplierShipTo, type SupplierStock, type SuppliersDefaultConfig, SuppliersFeature, type SuppliersPluginConfig, type SuppliersStaticConfig, type TabItem, type TabsBlock, type ToggleBlock, type TrackingEvent, TransactionStatus, type WebhookSignatureResult, analyticsCapability, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };
+export { ANALYTICS_PLUGIN_TOKEN, type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, type AnalyticsActionSource, type AnalyticsConsent, type AnalyticsEvent, type AnalyticsEventName, AnalyticsFeature, type AnalyticsItem, type AnalyticsMoney, type AnalyticsPluginConfig, type AnalyticsStaticConfig, type AnalyticsUserData, type AnalyticsUtm, type BannerBlock, type Block, type BlockBase, BlockType, type CalloutBlock, type Capability, CapabilityKind, type CardBlock, type CodConfig, type CodFeeConfig, CodFeeType, type ConditionalBlock, type ConditionalEquals, type ConditionalWhen, ConfigScope, type ConfigurablePlugin, type CopyFieldBlock, type CreateShipmentParams, type DispatchContext, type DividerBlock, type DomainEventHandler, type DomainEventName, type EmbedInit, type FieldBlock, type FieldDefinition, type FieldDependsOn, type FieldMap, type FieldOption, FieldType, FieldVariant, GatewayEnvironment, type GatewayStaticConfig, type GroupBlock, type HostApi, type HttpClient, type HttpRequest, type HttpResponse, type IAnalyticsPlugin, type IInvoicingPlugin, INVOICING_PLUGIN_TOKEN, type IPaymentPlugin, type IPlugin, type IShippingPlugin, type ISuppliersPlugin, type InlineRowBlock, InvoiceDocumentType, type InvoiceLine, type InvoiceMoney, type InvoiceParty, type InvoiceRequest, type InvoiceResult, InvoiceStatus, type InvoiceTax, type InvoicingDefaultConfig, InvoicingFeature, type InvoicingPluginConfig, type InvoicingStaticConfig, type KeyValueBlock, type KeyValueRow, LayoutMode, type Logger, type MarkdownBlock, MessageVariant, PAYMENT_PLUGIN_TOKEN, type PaymentCard, type PaymentCustomer, type PaymentGatewayCode, type PaymentPayload, type PaymentPluginConfig, type PaymentRenderMode, type PaymentResult, type PaymentSessionPayload, type PaymentSessionResult, type PaymentVerifyPayload, type Permission, type PermissionCheck, type PlaceSupplierOrderInput, type Plugin, type PluginActionContext, type PluginActionResult, type PluginConfigField, type PluginConfigFieldDependency, type PluginConfigResult, type PluginConfigValidation, type PluginFactory, type PluginManifest, PluginType, type RepeaterBlock, RepeaterSource, SDK_VERSION, SHIPPING_PLUGIN_TOKEN, SUPPLIERS_PLUGIN_TOKEN, type SecretStore, type SelectOption, type SequenceStore, type SetupAction, type SetupLayout, type SetupLayoutValidation, type SetupStep, type ShipmentAddress, type ShipmentParcel, type ShipmentResult, type ShippingDefaultConfig, ShippingFeature, type ShippingPluginConfig, type ShippingQuote, type ShippingQuoteParams, type ShippingStaticConfig, StepStatusFrom, type StepStatusFromAction, type StepStatusFromFields, type StepStatusSource, type StorageBroker, type SupplierCatalogQuery, type SupplierFulfillmentEvent, type SupplierListing, type SupplierListingAttribute, type SupplierListingPage, type SupplierListingVariant, type SupplierMoney, type SupplierOrderAddressLevel, type SupplierOrderCustomer, type SupplierOrderLine, type SupplierOrderResult, type SupplierOrderStatus, type SupplierShipTo, type SupplierStock, type SuppliersDefaultConfig, SuppliersFeature, type SuppliersPluginConfig, type SuppliersStaticConfig, type TabItem, type TabsBlock, type ToggleBlock, type TrackingEvent, TransactionStatus, type VoidInvoiceInput, type WebhookSignatureResult, analyticsCapability, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, invoicingCapability, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };

package/dist/index.js

@@ -30,6 +30,10 @@ __export(index_exports, {
   FieldType: () => FieldType,
   FieldVariant: () => FieldVariant,
   GatewayEnvironment: () => GatewayEnvironment,
+  INVOICING_PLUGIN_TOKEN: () => INVOICING_PLUGIN_TOKEN,
+  InvoiceDocumentType: () => InvoiceDocumentType,
+  InvoiceStatus: () => InvoiceStatus,
+  InvoicingFeature: () => InvoicingFeature,
   LayoutMode: () => LayoutMode,
   MessageVariant: () => MessageVariant,
   PAYMENT_PLUGIN_TOKEN: () => PAYMENT_PLUGIN_TOKEN,
@@ -49,6 +53,7 @@ __export(index_exports, {
   crossValidateSetupLayout: () => crossValidateSetupLayout,
   definePlugin: () => definePlugin,
   field: () => field,
+  invoicingCapability: () => invoicingCapability,
   isConfigurablePlugin: () => isConfigurablePlugin,
   isPermissionGranted: () => isPermissionGranted,
   isPluginFactory: () => isPluginFactory,
@@ -66,12 +71,14 @@ var PAYMENT_PLUGIN_TOKEN = "PAYMENT_PLUGINS";
 var SHIPPING_PLUGIN_TOKEN = "SHIPPING_PLUGINS";
 var SUPPLIERS_PLUGIN_TOKEN = "SUPPLIERS_PLUGINS";
 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 || {});
@@ -211,6 +218,32 @@ var AnalyticsFeature = /* @__PURE__ */ ((AnalyticsFeature2) => {
   return AnalyticsFeature2;
 })(AnalyticsFeature || {});
 
+// src/invoicing.ts
+var InvoicingFeature = /* @__PURE__ */ ((InvoicingFeature2) => {
+  InvoicingFeature2["Issue"] = "issue";
+  InvoicingFeature2["Void"] = "void";
+  InvoicingFeature2["StatusQuery"] = "status-query";
+  InvoicingFeature2["Pdf"] = "pdf";
+  return InvoicingFeature2;
+})(InvoicingFeature || {});
+var InvoiceDocumentType = /* @__PURE__ */ ((InvoiceDocumentType2) => {
+  InvoiceDocumentType2["Invoice"] = "invoice";
+  InvoiceDocumentType2["CreditInvoice"] = "credit-invoice";
+  InvoiceDocumentType2["CreditNote"] = "credit-note";
+  InvoiceDocumentType2["DebitNote"] = "debit-note";
+  InvoiceDocumentType2["ExcludedSubject"] = "excluded-subject";
+  InvoiceDocumentType2["Export"] = "export";
+  return InvoiceDocumentType2;
+})(InvoiceDocumentType || {});
+var InvoiceStatus = /* @__PURE__ */ ((InvoiceStatus2) => {
+  InvoiceStatus2["Pending"] = "pending";
+  InvoiceStatus2["Accepted"] = "accepted";
+  InvoiceStatus2["Rejected"] = "rejected";
+  InvoiceStatus2["Voided"] = "voided";
+  InvoiceStatus2["Unknown"] = "unknown";
+  return InvoiceStatus2;
+})(InvoiceStatus || {});
+
 // src/setup-layout.ts
 var import_superstruct2 = require("superstruct");
 var FieldVariant = /* @__PURE__ */ ((FieldVariant2) => {
@@ -482,7 +515,8 @@ var CapabilityKind = {
   Payment: "payment",
   Shipping: "shipping",
   Suppliers: "suppliers",
-  Analytics: "analytics"
+  Analytics: "analytics",
+  Invoicing: "invoicing"
 };
 function capability(kind, impl) {
   return { kind, impl };
@@ -499,6 +533,9 @@ function suppliersCapability(impl) {
 function analyticsCapability(impl) {
   return { kind: CapabilityKind.Analytics, impl };
 }
+function invoicingCapability(impl) {
+  return { kind: CapabilityKind.Invoicing, impl };
+}
 var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
 function definePlugin(factory) {
   Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
@@ -544,7 +581,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.6.2";
+var SDK_VERSION = "0.6.5";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -571,6 +608,10 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   FieldType,
   FieldVariant,
   GatewayEnvironment,
+  INVOICING_PLUGIN_TOKEN,
+  InvoiceDocumentType,
+  InvoiceStatus,
+  InvoicingFeature,
   LayoutMode,
   MessageVariant,
   PAYMENT_PLUGIN_TOKEN,
@@ -590,6 +631,7 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   crossValidateSetupLayout,
   definePlugin,
   field,
+  invoicingCapability,
   isConfigurablePlugin,
   isPermissionGranted,
   isPluginFactory,

package/dist/index.mjs

@@ -3,12 +3,14 @@ var PAYMENT_PLUGIN_TOKEN = "PAYMENT_PLUGINS";
 var SHIPPING_PLUGIN_TOKEN = "SHIPPING_PLUGINS";
 var SUPPLIERS_PLUGIN_TOKEN = "SUPPLIERS_PLUGINS";
 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 || {});
@@ -156,6 +158,32 @@ var AnalyticsFeature = /* @__PURE__ */ ((AnalyticsFeature2) => {
   return AnalyticsFeature2;
 })(AnalyticsFeature || {});
 
+// src/invoicing.ts
+var InvoicingFeature = /* @__PURE__ */ ((InvoicingFeature2) => {
+  InvoicingFeature2["Issue"] = "issue";
+  InvoicingFeature2["Void"] = "void";
+  InvoicingFeature2["StatusQuery"] = "status-query";
+  InvoicingFeature2["Pdf"] = "pdf";
+  return InvoicingFeature2;
+})(InvoicingFeature || {});
+var InvoiceDocumentType = /* @__PURE__ */ ((InvoiceDocumentType2) => {
+  InvoiceDocumentType2["Invoice"] = "invoice";
+  InvoiceDocumentType2["CreditInvoice"] = "credit-invoice";
+  InvoiceDocumentType2["CreditNote"] = "credit-note";
+  InvoiceDocumentType2["DebitNote"] = "debit-note";
+  InvoiceDocumentType2["ExcludedSubject"] = "excluded-subject";
+  InvoiceDocumentType2["Export"] = "export";
+  return InvoiceDocumentType2;
+})(InvoiceDocumentType || {});
+var InvoiceStatus = /* @__PURE__ */ ((InvoiceStatus2) => {
+  InvoiceStatus2["Pending"] = "pending";
+  InvoiceStatus2["Accepted"] = "accepted";
+  InvoiceStatus2["Rejected"] = "rejected";
+  InvoiceStatus2["Voided"] = "voided";
+  InvoiceStatus2["Unknown"] = "unknown";
+  return InvoiceStatus2;
+})(InvoiceStatus || {});
+
 // src/setup-layout.ts
 import {
   array,
@@ -440,7 +468,8 @@ var CapabilityKind = {
   Payment: "payment",
   Shipping: "shipping",
   Suppliers: "suppliers",
-  Analytics: "analytics"
+  Analytics: "analytics",
+  Invoicing: "invoicing"
 };
 function capability(kind, impl) {
   return { kind, impl };
@@ -457,6 +486,9 @@ function suppliersCapability(impl) {
 function analyticsCapability(impl) {
   return { kind: CapabilityKind.Analytics, impl };
 }
+function invoicingCapability(impl) {
+  return { kind: CapabilityKind.Invoicing, impl };
+}
 var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
 function definePlugin(factory) {
   Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
@@ -502,7 +534,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.6.2";
+var SDK_VERSION = "0.6.5";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -528,6 +560,10 @@ export {
   FieldType,
   FieldVariant,
   GatewayEnvironment,
+  INVOICING_PLUGIN_TOKEN,
+  InvoiceDocumentType,
+  InvoiceStatus,
+  InvoicingFeature,
   LayoutMode,
   MessageVariant,
   PAYMENT_PLUGIN_TOKEN,
@@ -547,6 +583,7 @@ export {
   crossValidateSetupLayout,
   definePlugin,
   field,
+  invoicingCapability,
   isConfigurablePlugin,
   isPermissionGranted,
   isPluginFactory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivoa/plugin-sdk",
-  "version": "0.6.2",
+  "version": "0.6.5",
   "description": "Public contracts for Vivoa plugins (types, DI tokens, config + setup-layout validators)",
   "license": "MIT",
   "author": "Vivoa",