@vivoa/plugin-sdk 0.6.2 → 0.6.3

package/dist/index.d.mts

@@ -473,6 +473,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 +487,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 +559,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 {
@@ -1171,7 +1232,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.3";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -1180,4 +1241,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 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 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 WebhookSignatureResult, analyticsCapability, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };

package/dist/index.d.ts

@@ -473,6 +473,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 +487,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 +559,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 {
@@ -1171,7 +1232,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.3";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -1180,4 +1241,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 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 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 WebhookSignatureResult, analyticsCapability, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };

package/dist/index.js

@@ -544,7 +544,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.6.2";
+var SDK_VERSION = "0.6.3";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);

package/dist/index.mjs

@@ -502,7 +502,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.6.2";
+var SDK_VERSION = "0.6.3";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);

package/package.json

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