@vivoa/plugin-sdk 0.5.0 → 0.5.2

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 declare const PAYMENT_PLUGIN_TOKEN: "PAYMENT_PLUGINS";
 declare const SHIPPING_PLUGIN_TOKEN: "SHIPPING_PLUGINS";
+declare const SUPPLIERS_PLUGIN_TOKEN: "SUPPLIERS_PLUGINS";
 
 declare enum FieldType {
     String = "string",
@@ -509,7 +510,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 +618,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 +643,191 @@ 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;
+}
+
+declare enum SuppliersFeature {
+    /** Browse/search the supplier catalog. */
+    CatalogSearch = "catalog-search",
+    /** Pull a full listing snapshot to seed a native product. */
+    CatalogImport = "catalog-import",
+    /** Place + track orders against the supplier. */
+    Orders = "orders",
+    /** Supplier pushes order status to a registered webhook. */
+    FulfillmentSync = "fulfillment-sync",
+    /**
+     * Poll the supplier for stock levels. SoyDrop has no inventory webhook, so
+     * stock is reconciled by polling rather than push.
+     */
+    StockSync = "stock-sync"
+}
+/**
+ * ISO-4217 money in minor units — mirrors the store's Money VO
+ * (`core/source/contracts/source-dtos.ts`) so the host maps 1:1 without a
+ * currency guess. Kept local so the SDK stays dependency-free.
+ */
+interface SupplierMoney {
+    amountMinor: number;
+    currency: string;
+}
+interface SuppliersDefaultConfig {
+    global?: Record<string, unknown>;
+    countries?: Record<string, Record<string, unknown>>;
+}
+interface SuppliersPluginConfig {
+    supportedCountries: string[];
+    supportedCapabilities: SuppliersFeature[];
+    configSchema: PluginConfigField[];
+    defaultConfig?: SuppliersDefaultConfig;
+}
+interface SuppliersStaticConfig {
+    code: string;
+    displayName: string;
+    description: string;
+    iconUrl?: string;
+    supportedCountries: string[];
+    supportedCapabilities: SuppliersFeature[];
+    configSchema: PluginConfigField[];
+}
+interface SupplierCatalogQuery {
+    text?: string;
+    country?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface SupplierListingVariant {
+    externalVariantId: string;
+    sku?: string | null;
+    title: string;
+    wholesalePrice: SupplierMoney;
+    options?: Record<string, string>;
+    imageUrl?: string | null;
+    available?: boolean;
+}
+interface SupplierListingAttribute {
+    name: string;
+    value: string;
+}
+interface SupplierStock {
+    externalId: string;
+    quantity: number;
+    inStock: boolean;
+}
+interface SupplierListing {
+    /** Native id in the supplier catalog (product or catalog-item id). */
+    externalId: string;
+    title: string;
+    description?: string | null;
+    sku?: string | null;
+    /** ABSOLUTE image URLs. `imageUrl` is the primary; `images` the gallery. */
+    imageUrl?: string | null;
+    images?: string[];
+    /** Wholesale cost the merchant pays the supplier (per unit). */
+    wholesalePrice: SupplierMoney;
+    /** Supplier's suggested retail, when provided. */
+    suggestedPrice?: SupplierMoney | null;
+    stock: SupplierStock;
+    categories?: string[];
+    attributes?: SupplierListingAttribute[];
+    hasVariants: boolean;
+    variants?: SupplierListingVariant[];
+    moq?: number | null;
+    /** Untouched supplier payload, for diagnostics. Never trusted for control flow. */
+    raw?: unknown;
+}
+interface SupplierListingPage {
+    items: SupplierListing[];
+    nextCursor?: string | null;
+}
+interface SupplierOrderCustomer {
+    name: string;
+    lastName?: string | null;
+    phoneAreaCode: string;
+    phone: string;
+    email?: string | null;
+}
+interface SupplierOrderAddressLevel {
+    levelKey: string;
+    valueId: string;
+}
+interface SupplierShipTo {
+    address: string;
+    referencePoint?: string | null;
+    /** Supplier geo ids — resolved against the supplier's own geo endpoints. */
+    stateId: string;
+    cityId: string;
+    extraLevels?: SupplierOrderAddressLevel[];
+    latitude?: number;
+    longitude?: number;
+    instructions?: string | null;
+}
+interface SupplierOrderLine {
+    /** Supplier catalog/variant id to order. */
+    externalListingId: string;
+    quantity: number;
+    /** Optional price override; omit to use the supplier's catalog price. */
+    unitPrice?: SupplierMoney | null;
+}
+interface PlaceSupplierOrderInput {
+    /** Host order id — the idempotency key the supplier dedupes on. */
+    externalOrderId: string;
+    customer: SupplierOrderCustomer;
+    shipTo: SupplierShipTo;
+    lines: SupplierOrderLine[];
+    cod: boolean;
+    /** Exact amount to collect on COD; defaults to the line total. */
+    codAmount?: SupplierMoney | null;
+    /** Optional carrier choice; the supplier picks a default when omitted. */
+    courierId?: string | null;
+    note?: string | null;
+}
+/**
+ * Normalized supplier-order status. `unknown` is a first-class value for
+ * supplier states the adapter does not map — the host treats it as a no-op.
+ */
+type SupplierOrderStatus = 'pending' | 'accepted' | 'in_transit' | 'shipped' | 'delivered' | 'cancelled' | 'rejected' | 'unknown';
+interface SupplierOrderResult {
+    /** Supplier-side order id. */
+    externalId: string;
+    orderNumber?: string | null;
+    /** The host order id echoed back, when the supplier stores it. */
+    externalOrderId?: string | null;
+    status: SupplierOrderStatus;
+    statusLabel?: string | null;
+    trackingCode?: string | null;
+    trackingUrl?: string | null;
+    carrier?: string | null;
+    shippingCost?: SupplierMoney | null;
+    codAmount?: SupplierMoney | null;
+    raw?: unknown;
+}
+/**
+ * Normalized, supplier-agnostic fulfillment event produced by
+ * {@link ISuppliersPlugin.parseWebhook}. The host matches `externalOrderId`
+ * against its stored SupplierOrder to resolve the local order, so the adapter
+ * never needs host identifiers.
+ */
+interface SupplierFulfillmentEvent {
+    externalOrderId: string;
+    status: SupplierOrderStatus;
+    trackingCode?: string | null;
+    carrier?: string | null;
+    /** ISO-8601 instant the supplier reported the change, when available. */
+    occurredAt?: string;
+    statusDescription?: string;
+    /** Untouched supplier payload, for diagnostics. */
+    raw?: unknown;
+}
+interface ISuppliersPlugin extends IPlugin {
+    readonly name: string;
+    readonly suppliersConfig: SuppliersPluginConfig;
+    searchCatalog(query: SupplierCatalogQuery, ctx: DispatchContext): Promise<SupplierListingPage>;
+    getListing(externalId: string, ctx: DispatchContext): Promise<SupplierListing>;
+    placeOrder(order: PlaceSupplierOrderInput, ctx: DispatchContext): Promise<SupplierOrderResult>;
+    getOrderStatus(externalOrderId: string, ctx: DispatchContext): Promise<SupplierOrderResult>;
+    syncStock?(externalIds: string[], ctx: DispatchContext): Promise<SupplierStock[]>;
+    parseWebhook?(body: unknown, headers: Record<string, string>, ctx: DispatchContext): SupplierFulfillmentEvent | null;
     isConfigured?(ctx: DispatchContext): boolean;
 }
 
@@ -633,12 +844,14 @@ interface Capability<T = unknown> {
 declare const CapabilityKind: {
     readonly Payment: "payment";
     readonly Shipping: "shipping";
+    readonly Suppliers: "suppliers";
     readonly Analytics: "analytics";
 };
 type CapabilityKind = (typeof CapabilityKind)[keyof typeof CapabilityKind];
 declare function capability<T>(kind: string, impl: T): Capability<T>;
 declare function paymentCapability(impl: IPaymentPlugin): Capability<IPaymentPlugin>;
 declare function shippingCapability(impl: IShippingPlugin): Capability<IShippingPlugin>;
+declare function suppliersCapability(impl: ISuppliersPlugin): Capability<ISuppliersPlugin>;
 /**
  * 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
@@ -776,7 +989,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.2";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -785,4 +998,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 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, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 declare const PAYMENT_PLUGIN_TOKEN: "PAYMENT_PLUGINS";
 declare const SHIPPING_PLUGIN_TOKEN: "SHIPPING_PLUGINS";
+declare const SUPPLIERS_PLUGIN_TOKEN: "SUPPLIERS_PLUGINS";
 
 declare enum FieldType {
     String = "string",
@@ -509,7 +510,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 +618,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 +643,191 @@ 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;
+}
+
+declare enum SuppliersFeature {
+    /** Browse/search the supplier catalog. */
+    CatalogSearch = "catalog-search",
+    /** Pull a full listing snapshot to seed a native product. */
+    CatalogImport = "catalog-import",
+    /** Place + track orders against the supplier. */
+    Orders = "orders",
+    /** Supplier pushes order status to a registered webhook. */
+    FulfillmentSync = "fulfillment-sync",
+    /**
+     * Poll the supplier for stock levels. SoyDrop has no inventory webhook, so
+     * stock is reconciled by polling rather than push.
+     */
+    StockSync = "stock-sync"
+}
+/**
+ * ISO-4217 money in minor units — mirrors the store's Money VO
+ * (`core/source/contracts/source-dtos.ts`) so the host maps 1:1 without a
+ * currency guess. Kept local so the SDK stays dependency-free.
+ */
+interface SupplierMoney {
+    amountMinor: number;
+    currency: string;
+}
+interface SuppliersDefaultConfig {
+    global?: Record<string, unknown>;
+    countries?: Record<string, Record<string, unknown>>;
+}
+interface SuppliersPluginConfig {
+    supportedCountries: string[];
+    supportedCapabilities: SuppliersFeature[];
+    configSchema: PluginConfigField[];
+    defaultConfig?: SuppliersDefaultConfig;
+}
+interface SuppliersStaticConfig {
+    code: string;
+    displayName: string;
+    description: string;
+    iconUrl?: string;
+    supportedCountries: string[];
+    supportedCapabilities: SuppliersFeature[];
+    configSchema: PluginConfigField[];
+}
+interface SupplierCatalogQuery {
+    text?: string;
+    country?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface SupplierListingVariant {
+    externalVariantId: string;
+    sku?: string | null;
+    title: string;
+    wholesalePrice: SupplierMoney;
+    options?: Record<string, string>;
+    imageUrl?: string | null;
+    available?: boolean;
+}
+interface SupplierListingAttribute {
+    name: string;
+    value: string;
+}
+interface SupplierStock {
+    externalId: string;
+    quantity: number;
+    inStock: boolean;
+}
+interface SupplierListing {
+    /** Native id in the supplier catalog (product or catalog-item id). */
+    externalId: string;
+    title: string;
+    description?: string | null;
+    sku?: string | null;
+    /** ABSOLUTE image URLs. `imageUrl` is the primary; `images` the gallery. */
+    imageUrl?: string | null;
+    images?: string[];
+    /** Wholesale cost the merchant pays the supplier (per unit). */
+    wholesalePrice: SupplierMoney;
+    /** Supplier's suggested retail, when provided. */
+    suggestedPrice?: SupplierMoney | null;
+    stock: SupplierStock;
+    categories?: string[];
+    attributes?: SupplierListingAttribute[];
+    hasVariants: boolean;
+    variants?: SupplierListingVariant[];
+    moq?: number | null;
+    /** Untouched supplier payload, for diagnostics. Never trusted for control flow. */
+    raw?: unknown;
+}
+interface SupplierListingPage {
+    items: SupplierListing[];
+    nextCursor?: string | null;
+}
+interface SupplierOrderCustomer {
+    name: string;
+    lastName?: string | null;
+    phoneAreaCode: string;
+    phone: string;
+    email?: string | null;
+}
+interface SupplierOrderAddressLevel {
+    levelKey: string;
+    valueId: string;
+}
+interface SupplierShipTo {
+    address: string;
+    referencePoint?: string | null;
+    /** Supplier geo ids — resolved against the supplier's own geo endpoints. */
+    stateId: string;
+    cityId: string;
+    extraLevels?: SupplierOrderAddressLevel[];
+    latitude?: number;
+    longitude?: number;
+    instructions?: string | null;
+}
+interface SupplierOrderLine {
+    /** Supplier catalog/variant id to order. */
+    externalListingId: string;
+    quantity: number;
+    /** Optional price override; omit to use the supplier's catalog price. */
+    unitPrice?: SupplierMoney | null;
+}
+interface PlaceSupplierOrderInput {
+    /** Host order id — the idempotency key the supplier dedupes on. */
+    externalOrderId: string;
+    customer: SupplierOrderCustomer;
+    shipTo: SupplierShipTo;
+    lines: SupplierOrderLine[];
+    cod: boolean;
+    /** Exact amount to collect on COD; defaults to the line total. */
+    codAmount?: SupplierMoney | null;
+    /** Optional carrier choice; the supplier picks a default when omitted. */
+    courierId?: string | null;
+    note?: string | null;
+}
+/**
+ * Normalized supplier-order status. `unknown` is a first-class value for
+ * supplier states the adapter does not map — the host treats it as a no-op.
+ */
+type SupplierOrderStatus = 'pending' | 'accepted' | 'in_transit' | 'shipped' | 'delivered' | 'cancelled' | 'rejected' | 'unknown';
+interface SupplierOrderResult {
+    /** Supplier-side order id. */
+    externalId: string;
+    orderNumber?: string | null;
+    /** The host order id echoed back, when the supplier stores it. */
+    externalOrderId?: string | null;
+    status: SupplierOrderStatus;
+    statusLabel?: string | null;
+    trackingCode?: string | null;
+    trackingUrl?: string | null;
+    carrier?: string | null;
+    shippingCost?: SupplierMoney | null;
+    codAmount?: SupplierMoney | null;
+    raw?: unknown;
+}
+/**
+ * Normalized, supplier-agnostic fulfillment event produced by
+ * {@link ISuppliersPlugin.parseWebhook}. The host matches `externalOrderId`
+ * against its stored SupplierOrder to resolve the local order, so the adapter
+ * never needs host identifiers.
+ */
+interface SupplierFulfillmentEvent {
+    externalOrderId: string;
+    status: SupplierOrderStatus;
+    trackingCode?: string | null;
+    carrier?: string | null;
+    /** ISO-8601 instant the supplier reported the change, when available. */
+    occurredAt?: string;
+    statusDescription?: string;
+    /** Untouched supplier payload, for diagnostics. */
+    raw?: unknown;
+}
+interface ISuppliersPlugin extends IPlugin {
+    readonly name: string;
+    readonly suppliersConfig: SuppliersPluginConfig;
+    searchCatalog(query: SupplierCatalogQuery, ctx: DispatchContext): Promise<SupplierListingPage>;
+    getListing(externalId: string, ctx: DispatchContext): Promise<SupplierListing>;
+    placeOrder(order: PlaceSupplierOrderInput, ctx: DispatchContext): Promise<SupplierOrderResult>;
+    getOrderStatus(externalOrderId: string, ctx: DispatchContext): Promise<SupplierOrderResult>;
+    syncStock?(externalIds: string[], ctx: DispatchContext): Promise<SupplierStock[]>;
+    parseWebhook?(body: unknown, headers: Record<string, string>, ctx: DispatchContext): SupplierFulfillmentEvent | null;
     isConfigured?(ctx: DispatchContext): boolean;
 }
 
@@ -633,12 +844,14 @@ interface Capability<T = unknown> {
 declare const CapabilityKind: {
     readonly Payment: "payment";
     readonly Shipping: "shipping";
+    readonly Suppliers: "suppliers";
     readonly Analytics: "analytics";
 };
 type CapabilityKind = (typeof CapabilityKind)[keyof typeof CapabilityKind];
 declare function capability<T>(kind: string, impl: T): Capability<T>;
 declare function paymentCapability(impl: IPaymentPlugin): Capability<IPaymentPlugin>;
 declare function shippingCapability(impl: IShippingPlugin): Capability<IShippingPlugin>;
+declare function suppliersCapability(impl: ISuppliersPlugin): Capability<ISuppliersPlugin>;
 /**
  * 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
@@ -776,7 +989,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.2";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -785,4 +998,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 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, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };

package/dist/index.js

@@ -35,8 +35,10 @@ __export(index_exports, {
   RepeaterSource: () => RepeaterSource,
   SDK_VERSION: () => SDK_VERSION,
   SHIPPING_PLUGIN_TOKEN: () => SHIPPING_PLUGIN_TOKEN,
+  SUPPLIERS_PLUGIN_TOKEN: () => SUPPLIERS_PLUGIN_TOKEN,
   ShippingFeature: () => ShippingFeature,
   StepStatusFrom: () => StepStatusFrom,
+  SuppliersFeature: () => SuppliersFeature,
   TransactionStatus: () => TransactionStatus,
   capability: () => capability,
   checkPermissions: () => checkPermissions,
@@ -51,6 +53,7 @@ __export(index_exports, {
   parsePermission: () => parsePermission,
   paymentCapability: () => paymentCapability,
   shippingCapability: () => shippingCapability,
+  suppliersCapability: () => suppliersCapability,
   validateSetupLayout: () => validateSetupLayout
 });
 module.exports = __toCommonJS(index_exports);
@@ -58,6 +61,7 @@ module.exports = __toCommonJS(index_exports);
 // src/tokens.ts
 var PAYMENT_PLUGIN_TOKEN = "PAYMENT_PLUGINS";
 var SHIPPING_PLUGIN_TOKEN = "SHIPPING_PLUGINS";
+var SUPPLIERS_PLUGIN_TOKEN = "SUPPLIERS_PLUGINS";
 
 // src/plugin.ts
 var PluginType = /* @__PURE__ */ ((PluginType2) => {
@@ -177,6 +181,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) => {
@@ -185,6 +190,16 @@ var CodFeeType = /* @__PURE__ */ ((CodFeeType2) => {
   return CodFeeType2;
 })(CodFeeType || {});
 
+// src/suppliers.ts
+var SuppliersFeature = /* @__PURE__ */ ((SuppliersFeature2) => {
+  SuppliersFeature2["CatalogSearch"] = "catalog-search";
+  SuppliersFeature2["CatalogImport"] = "catalog-import";
+  SuppliersFeature2["Orders"] = "orders";
+  SuppliersFeature2["FulfillmentSync"] = "fulfillment-sync";
+  SuppliersFeature2["StockSync"] = "stock-sync";
+  return SuppliersFeature2;
+})(SuppliersFeature || {});
+
 // src/setup-layout.ts
 var import_superstruct2 = require("superstruct");
 var FieldVariant = /* @__PURE__ */ ((FieldVariant2) => {
@@ -455,6 +470,7 @@ function crossValidateSetupLayout(layout, configSchema) {
 var CapabilityKind = {
   Payment: "payment",
   Shipping: "shipping",
+  Suppliers: "suppliers",
   Analytics: "analytics"
 };
 function capability(kind, impl) {
@@ -466,6 +482,9 @@ function paymentCapability(impl) {
 function shippingCapability(impl) {
   return { kind: CapabilityKind.Shipping, impl };
 }
+function suppliersCapability(impl) {
+  return { kind: CapabilityKind.Suppliers, impl };
+}
 var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
 function definePlugin(factory) {
   Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
@@ -511,7 +530,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.2";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -543,8 +562,10 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   RepeaterSource,
   SDK_VERSION,
   SHIPPING_PLUGIN_TOKEN,
+  SUPPLIERS_PLUGIN_TOKEN,
   ShippingFeature,
   StepStatusFrom,
+  SuppliersFeature,
   TransactionStatus,
   capability,
   checkPermissions,
@@ -559,5 +580,6 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   parsePermission,
   paymentCapability,
   shippingCapability,
+  suppliersCapability,
   validateSetupLayout
 });

package/dist/index.mjs

@@ -1,6 +1,7 @@
 // src/tokens.ts
 var PAYMENT_PLUGIN_TOKEN = "PAYMENT_PLUGINS";
 var SHIPPING_PLUGIN_TOKEN = "SHIPPING_PLUGINS";
+var SUPPLIERS_PLUGIN_TOKEN = "SUPPLIERS_PLUGINS";
 
 // src/plugin.ts
 var PluginType = /* @__PURE__ */ ((PluginType2) => {
@@ -128,6 +129,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) => {
@@ -136,6 +138,16 @@ var CodFeeType = /* @__PURE__ */ ((CodFeeType2) => {
   return CodFeeType2;
 })(CodFeeType || {});
 
+// src/suppliers.ts
+var SuppliersFeature = /* @__PURE__ */ ((SuppliersFeature2) => {
+  SuppliersFeature2["CatalogSearch"] = "catalog-search";
+  SuppliersFeature2["CatalogImport"] = "catalog-import";
+  SuppliersFeature2["Orders"] = "orders";
+  SuppliersFeature2["FulfillmentSync"] = "fulfillment-sync";
+  SuppliersFeature2["StockSync"] = "stock-sync";
+  return SuppliersFeature2;
+})(SuppliersFeature || {});
+
 // src/setup-layout.ts
 import {
   array,
@@ -419,6 +431,7 @@ function crossValidateSetupLayout(layout, configSchema) {
 var CapabilityKind = {
   Payment: "payment",
   Shipping: "shipping",
+  Suppliers: "suppliers",
   Analytics: "analytics"
 };
 function capability(kind, impl) {
@@ -430,6 +443,9 @@ function paymentCapability(impl) {
 function shippingCapability(impl) {
   return { kind: CapabilityKind.Shipping, impl };
 }
+function suppliersCapability(impl) {
+  return { kind: CapabilityKind.Suppliers, impl };
+}
 var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
 function definePlugin(factory) {
   Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
@@ -475,7 +491,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.2";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -506,8 +522,10 @@ export {
   RepeaterSource,
   SDK_VERSION,
   SHIPPING_PLUGIN_TOKEN,
+  SUPPLIERS_PLUGIN_TOKEN,
   ShippingFeature,
   StepStatusFrom,
+  SuppliersFeature,
   TransactionStatus,
   capability,
   checkPermissions,
@@ -522,5 +540,6 @@ export {
   parsePermission,
   paymentCapability,
   shippingCapability,
+  suppliersCapability,
   validateSetupLayout
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivoa/plugin-sdk",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Public contracts for Vivoa plugins (types, DI tokens, config + setup-layout validators)",
   "license": "MIT",
   "author": "Vivoa",
@@ -56,4 +56,4 @@
       "esbuild"
     ]
   }
-}
+}