@vivoa/plugin-sdk 0.5.0 → 0.5.1

package/dist/index.d.mts

@@ -509,7 +509,14 @@ declare enum ShippingFeature {
     Tracking = "tracking",
     Cod = "cod",
     Quotes = "quotes",
-    Labels = "labels"
+    Labels = "labels",
+    /**
+     * The carrier pushes shipment status changes to a registered webhook URL,
+     * and the plugin can normalize + authenticate that payload via
+     * {@link IShippingPlugin.parseWebhook}. Enables unattended order transitions
+     * (e.g. → delivered) instead of manual admin updates.
+     */
+    TrackingSync = "tracking-sync"
 }
 declare enum CodFeeType {
     Percentage = "percentage",
@@ -610,6 +617,24 @@ interface ShipmentResult {
     status: string;
     rawResponse?: Record<string, unknown>;
 }
+/**
+ * Normalized, carrier-agnostic shipment status event produced by
+ * {@link IShippingPlugin.parseWebhook}. The host matches `trackingNumber`
+ * against its stored shipment to resolve the order, so the plugin never needs
+ * host identifiers. `status: 'unknown'` is a first-class value for carrier
+ * states the plugin does not map — the host treats it as a no-op instead of
+ * guessing a transition.
+ */
+interface TrackingEvent {
+    trackingNumber: string;
+    status: 'in_transit' | 'delivered' | 'cancelled' | 'unknown';
+    /** ISO-8601 instant the carrier reported the change, when available. */
+    occurredAt?: string;
+    /** Human-readable carrier status, for audit/logging. */
+    statusDescription?: string;
+    /** Untouched carrier payload, for diagnostics. Never trusted for control flow. */
+    raw?: unknown;
+}
 interface IShippingPlugin extends IPlugin {
     readonly name: string;
     readonly shippingConfig: ShippingPluginConfig;
@@ -617,6 +642,7 @@ interface IShippingPlugin extends IPlugin {
     getQuotes?(params: ShippingQuoteParams, ctx: DispatchContext): Promise<ShippingQuote[]>;
     /** Pure — a tracking URL never depends on tenant config. */
     getTrackingUrl(trackingNumber: string): string;
+    parseWebhook?(body: unknown, headers: Record<string, string>, ctx: DispatchContext): TrackingEvent | null;
     isConfigured?(ctx: DispatchContext): boolean;
 }
 
@@ -776,7 +802,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.5.0";
+declare const SDK_VERSION = "0.5.1";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -785,4 +811,4 @@ declare const SDK_VERSION = "0.5.0";
  */
 declare function isSdkCompatible(pluginSdkVersion: string, hostSdkVersion: string): boolean;
 
-export { type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, 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 IPaymentPlugin, type IPlugin, type IShippingPlugin, 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 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, 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 TabItem, type TabsBlock, type ToggleBlock, TransactionStatus, type WebhookSignatureResult, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, validateSetupLayout };
+export { type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, 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 IPaymentPlugin, type IPlugin, type IShippingPlugin, 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 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, 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 TabItem, type TabsBlock, type ToggleBlock, type TrackingEvent, TransactionStatus, type WebhookSignatureResult, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, validateSetupLayout };

package/dist/index.d.ts

@@ -509,7 +509,14 @@ declare enum ShippingFeature {
     Tracking = "tracking",
     Cod = "cod",
     Quotes = "quotes",
-    Labels = "labels"
+    Labels = "labels",
+    /**
+     * The carrier pushes shipment status changes to a registered webhook URL,
+     * and the plugin can normalize + authenticate that payload via
+     * {@link IShippingPlugin.parseWebhook}. Enables unattended order transitions
+     * (e.g. → delivered) instead of manual admin updates.
+     */
+    TrackingSync = "tracking-sync"
 }
 declare enum CodFeeType {
     Percentage = "percentage",
@@ -610,6 +617,24 @@ interface ShipmentResult {
     status: string;
     rawResponse?: Record<string, unknown>;
 }
+/**
+ * Normalized, carrier-agnostic shipment status event produced by
+ * {@link IShippingPlugin.parseWebhook}. The host matches `trackingNumber`
+ * against its stored shipment to resolve the order, so the plugin never needs
+ * host identifiers. `status: 'unknown'` is a first-class value for carrier
+ * states the plugin does not map — the host treats it as a no-op instead of
+ * guessing a transition.
+ */
+interface TrackingEvent {
+    trackingNumber: string;
+    status: 'in_transit' | 'delivered' | 'cancelled' | 'unknown';
+    /** ISO-8601 instant the carrier reported the change, when available. */
+    occurredAt?: string;
+    /** Human-readable carrier status, for audit/logging. */
+    statusDescription?: string;
+    /** Untouched carrier payload, for diagnostics. Never trusted for control flow. */
+    raw?: unknown;
+}
 interface IShippingPlugin extends IPlugin {
     readonly name: string;
     readonly shippingConfig: ShippingPluginConfig;
@@ -617,6 +642,7 @@ interface IShippingPlugin extends IPlugin {
     getQuotes?(params: ShippingQuoteParams, ctx: DispatchContext): Promise<ShippingQuote[]>;
     /** Pure — a tracking URL never depends on tenant config. */
     getTrackingUrl(trackingNumber: string): string;
+    parseWebhook?(body: unknown, headers: Record<string, string>, ctx: DispatchContext): TrackingEvent | null;
     isConfigured?(ctx: DispatchContext): boolean;
 }
 
@@ -776,7 +802,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.5.0";
+declare const SDK_VERSION = "0.5.1";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -785,4 +811,4 @@ declare const SDK_VERSION = "0.5.0";
  */
 declare function isSdkCompatible(pluginSdkVersion: string, hostSdkVersion: string): boolean;
 
-export { type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, 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 IPaymentPlugin, type IPlugin, type IShippingPlugin, 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 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, 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 TabItem, type TabsBlock, type ToggleBlock, TransactionStatus, type WebhookSignatureResult, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, validateSetupLayout };
+export { type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, 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 IPaymentPlugin, type IPlugin, type IShippingPlugin, 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 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, 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 TabItem, type TabsBlock, type ToggleBlock, type TrackingEvent, TransactionStatus, type WebhookSignatureResult, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, validateSetupLayout };

package/dist/index.js

@@ -177,6 +177,7 @@ var ShippingFeature = /* @__PURE__ */ ((ShippingFeature2) => {
   ShippingFeature2["Cod"] = "cod";
   ShippingFeature2["Quotes"] = "quotes";
   ShippingFeature2["Labels"] = "labels";
+  ShippingFeature2["TrackingSync"] = "tracking-sync";
   return ShippingFeature2;
 })(ShippingFeature || {});
 var CodFeeType = /* @__PURE__ */ ((CodFeeType2) => {
@@ -511,7 +512,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.1";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);

package/dist/index.mjs

@@ -128,6 +128,7 @@ var ShippingFeature = /* @__PURE__ */ ((ShippingFeature2) => {
   ShippingFeature2["Cod"] = "cod";
   ShippingFeature2["Quotes"] = "quotes";
   ShippingFeature2["Labels"] = "labels";
+  ShippingFeature2["TrackingSync"] = "tracking-sync";
   return ShippingFeature2;
 })(ShippingFeature || {});
 var CodFeeType = /* @__PURE__ */ ((CodFeeType2) => {
@@ -475,7 +476,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.1";
 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.5.0",
+  "version": "0.5.1",
   "description": "Public contracts for Vivoa plugins (types, DI tokens, config + setup-layout validators)",
   "license": "MIT",
   "author": "Vivoa",