@vivoa/plugin-sdk 0.6.0 → 0.6.2

package/dist/index.d.mts

@@ -1,6 +1,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 enum FieldType {
     String = "string",
@@ -843,6 +844,174 @@ interface ISuppliersPlugin extends IPlugin {
     isConfigured?(ctx: DispatchContext): boolean;
 }
 
+declare enum AnalyticsFeature {
+    /** Ecommerce funnel events: view_item, add_to_cart, begin_checkout, purchase. */
+    Ecommerce = "ecommerce",
+    /** Generic page_view tracking. */
+    PageViews = "page-views"
+}
+/**
+ * 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 AnalyticsMoney {
+    amountMinor: number;
+    currency: string;
+}
+/** A single line item attached to an ecommerce event. */
+interface AnalyticsItem {
+    /** Product id as the store knows it (Meta `content_ids`, GA4 `item_id`). */
+    id: string;
+    /** Variant id for catalog-level granularity, when the line resolves one. */
+    variantId?: string | null;
+    name?: string;
+    sku?: string | null;
+    /** Brand for catalog feeds that key on it. */
+    brand?: string | null;
+    quantity?: number;
+    price?: AnalyticsMoney;
+    category?: string | null;
+}
+/**
+ * Canonical, provider-agnostic event names the host emits. Closed set: the host
+ * only ever maps a domain event to one of these. An adapter that does not care
+ * about a given name simply ignores it.
+ */
+type AnalyticsEventName = 'page_view' | 'view_item' | 'add_to_cart' | 'remove_from_cart' | 'begin_checkout' | 'purchase';
+/**
+ * Where the action physically happened. Maps to Meta `action_source`; other
+ * providers ignore it. Defaults to `website` when the host omits it.
+ */
+type AnalyticsActionSource = 'website' | 'app' | 'server' | 'phone_call' | 'chat' | 'email' | 'physical_store' | 'other';
+/**
+ * Identity + match-quality signals. EVERYTHING here is optional — the host
+ * populates whatever it can resolve for the event in scope.
+ *
+ * @rule The `*Sha256` fields arrive ALREADY hashed by the host (SHA256 hex of
+ *       the normalized value: lowercased + trimmed; phone in E.164 digits).
+ *       The plugin NEVER receives raw PII. `externalId`, `clientIpAddress`,
+ *       `clientUserAgent` and the click ids are the exception — providers
+ *       require them PLAIN.
+ */
+interface AnalyticsUserData {
+    emailSha256?: string | null;
+    phoneSha256?: string | null;
+    firstNameSha256?: string | null;
+    lastNameSha256?: string | null;
+    citySha256?: string | null;
+    stateSha256?: string | null;
+    zipSha256?: string | null;
+    countrySha256?: string | null;
+    genderSha256?: string | null;
+    /** Date of birth, YYYYMMDD normalized then SHA256. */
+    dobSha256?: string | null;
+    /** Store customer/user id — Meta `external_id` (not hashed by spec). */
+    externalId?: string | null;
+    /** Plain IPv4/IPv6 — never hashed (geo match). */
+    clientIpAddress?: string | null;
+    /** Plain browser UA — never hashed (device match). */
+    clientUserAgent?: string | null;
+    /** Meta browser cookie `_fbp`. */
+    fbp?: string | null;
+    /** Meta click id `_fbc`. */
+    fbc?: string | null;
+    /** Google Ads click id. */
+    gclid?: string | null;
+    /** TikTok click id. */
+    ttclid?: string | null;
+}
+/** Marketing attribution captured at the session that led to the event. */
+interface AnalyticsUtm {
+    source?: string | null;
+    medium?: string | null;
+    campaign?: string | null;
+    term?: string | null;
+    content?: string | null;
+}
+/**
+ * Consent signals the host resolved for this event. Providers that honor
+ * consent (Meta LDU, Google Consent Mode) gate on it; others ignore it.
+ */
+interface AnalyticsConsent {
+    adStorage?: boolean;
+    adUserData?: boolean;
+    adPersonalization?: boolean;
+}
+/**
+ * Normalized analytics event. The host builds this from a DomainEvent and hands
+ * it to every active analytics adapter. The adapter translates it to its own
+ * wire format (GA4 event, Meta event, ...). See the @rule SUPERSET note at the
+ * top of the module: this is the superset of what Meta CAPI needs.
+ */
+interface AnalyticsEvent {
+    name: AnalyticsEventName;
+    /** ISO-8601 instant the underlying action happened. */
+    occurredAt: string;
+    /**
+     * Stable id for cross-channel deduplication against the browser pixel (Meta
+     * `event_id`). For `purchase` the host sets it to the order id so the pixel
+     * and the server event collapse into one.
+     */
+    eventId?: string | null;
+    /** Where the action happened — Meta `action_source`. Defaults to `website`. */
+    actionSource?: AnalyticsActionSource;
+    /**
+     * Pseudonymous client identity for sessionization (maps to GA4 `client_id`
+     * / Meta `external_id`). Null when the host cannot resolve a stable id.
+     */
+    clientId?: string | null;
+    sessionId?: string | null;
+    /** Hashed identity + client signals + click ids. See {@link AnalyticsUserData}. */
+    user?: AnalyticsUserData;
+    /** Monetary value for value-bearing events (purchase, begin_checkout). */
+    value?: AnalyticsMoney | null;
+    /** Order id for `purchase` — providers dedupe transactions on it. */
+    transactionId?: string | null;
+    items?: AnalyticsItem[];
+    /** Page context for `page_view`. */
+    pageLocation?: string | null;
+    /** Referring URL, when the host knows it. */
+    pageReferrer?: string | null;
+    pageTitle?: string | null;
+    /** Marketing attribution for the session that produced the event. */
+    utm?: AnalyticsUtm;
+    /** Consent signals resolved by the host for this event. */
+    consent?: AnalyticsConsent;
+    /** Extra params forwarded verbatim as custom dimensions. */
+    params?: Record<string, unknown>;
+}
+interface AnalyticsPluginConfig {
+    supportedCapabilities: AnalyticsFeature[];
+    configSchema: PluginConfigField[];
+    /** GLOBAL-scope defaults merged under the tenant DB config by the host. */
+    defaultConfig?: Record<string, unknown>;
+}
+interface AnalyticsStaticConfig {
+    code: string;
+    displayName: string;
+    description: string;
+    iconUrl?: string;
+    supportedCapabilities: AnalyticsFeature[];
+    configSchema: PluginConfigField[];
+}
+interface IAnalyticsPlugin extends IPlugin {
+    readonly name: string;
+    readonly analyticsConfig: AnalyticsPluginConfig;
+    /**
+     * Forward one canonical event to the provider's ingestion API. Stateless: the
+     * tenant's resolved credentials arrive in `ctx.config` on every call.
+     *
+     * @rule BEST-EFFORT — never throw on a transport/provider error. Analytics is
+     *       fire-and-forget and MUST NOT break the domain flow that triggered it.
+     */
+    track(event: AnalyticsEvent, ctx: DispatchContext): Promise<void>;
+    /**
+     * 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;
@@ -864,6 +1033,7 @@ 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>;
+declare function analyticsCapability(impl: IAnalyticsPlugin): Capability<IAnalyticsPlugin>;
 /**
  * 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
@@ -1001,7 +1171,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.0";
+declare const SDK_VERSION = "0.6.2";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -1010,4 +1180,4 @@ declare const SDK_VERSION = "0.6.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 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 };
+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 };

package/dist/index.d.ts

@@ -1,6 +1,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 enum FieldType {
     String = "string",
@@ -843,6 +844,174 @@ interface ISuppliersPlugin extends IPlugin {
     isConfigured?(ctx: DispatchContext): boolean;
 }
 
+declare enum AnalyticsFeature {
+    /** Ecommerce funnel events: view_item, add_to_cart, begin_checkout, purchase. */
+    Ecommerce = "ecommerce",
+    /** Generic page_view tracking. */
+    PageViews = "page-views"
+}
+/**
+ * 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 AnalyticsMoney {
+    amountMinor: number;
+    currency: string;
+}
+/** A single line item attached to an ecommerce event. */
+interface AnalyticsItem {
+    /** Product id as the store knows it (Meta `content_ids`, GA4 `item_id`). */
+    id: string;
+    /** Variant id for catalog-level granularity, when the line resolves one. */
+    variantId?: string | null;
+    name?: string;
+    sku?: string | null;
+    /** Brand for catalog feeds that key on it. */
+    brand?: string | null;
+    quantity?: number;
+    price?: AnalyticsMoney;
+    category?: string | null;
+}
+/**
+ * Canonical, provider-agnostic event names the host emits. Closed set: the host
+ * only ever maps a domain event to one of these. An adapter that does not care
+ * about a given name simply ignores it.
+ */
+type AnalyticsEventName = 'page_view' | 'view_item' | 'add_to_cart' | 'remove_from_cart' | 'begin_checkout' | 'purchase';
+/**
+ * Where the action physically happened. Maps to Meta `action_source`; other
+ * providers ignore it. Defaults to `website` when the host omits it.
+ */
+type AnalyticsActionSource = 'website' | 'app' | 'server' | 'phone_call' | 'chat' | 'email' | 'physical_store' | 'other';
+/**
+ * Identity + match-quality signals. EVERYTHING here is optional — the host
+ * populates whatever it can resolve for the event in scope.
+ *
+ * @rule The `*Sha256` fields arrive ALREADY hashed by the host (SHA256 hex of
+ *       the normalized value: lowercased + trimmed; phone in E.164 digits).
+ *       The plugin NEVER receives raw PII. `externalId`, `clientIpAddress`,
+ *       `clientUserAgent` and the click ids are the exception — providers
+ *       require them PLAIN.
+ */
+interface AnalyticsUserData {
+    emailSha256?: string | null;
+    phoneSha256?: string | null;
+    firstNameSha256?: string | null;
+    lastNameSha256?: string | null;
+    citySha256?: string | null;
+    stateSha256?: string | null;
+    zipSha256?: string | null;
+    countrySha256?: string | null;
+    genderSha256?: string | null;
+    /** Date of birth, YYYYMMDD normalized then SHA256. */
+    dobSha256?: string | null;
+    /** Store customer/user id — Meta `external_id` (not hashed by spec). */
+    externalId?: string | null;
+    /** Plain IPv4/IPv6 — never hashed (geo match). */
+    clientIpAddress?: string | null;
+    /** Plain browser UA — never hashed (device match). */
+    clientUserAgent?: string | null;
+    /** Meta browser cookie `_fbp`. */
+    fbp?: string | null;
+    /** Meta click id `_fbc`. */
+    fbc?: string | null;
+    /** Google Ads click id. */
+    gclid?: string | null;
+    /** TikTok click id. */
+    ttclid?: string | null;
+}
+/** Marketing attribution captured at the session that led to the event. */
+interface AnalyticsUtm {
+    source?: string | null;
+    medium?: string | null;
+    campaign?: string | null;
+    term?: string | null;
+    content?: string | null;
+}
+/**
+ * Consent signals the host resolved for this event. Providers that honor
+ * consent (Meta LDU, Google Consent Mode) gate on it; others ignore it.
+ */
+interface AnalyticsConsent {
+    adStorage?: boolean;
+    adUserData?: boolean;
+    adPersonalization?: boolean;
+}
+/**
+ * Normalized analytics event. The host builds this from a DomainEvent and hands
+ * it to every active analytics adapter. The adapter translates it to its own
+ * wire format (GA4 event, Meta event, ...). See the @rule SUPERSET note at the
+ * top of the module: this is the superset of what Meta CAPI needs.
+ */
+interface AnalyticsEvent {
+    name: AnalyticsEventName;
+    /** ISO-8601 instant the underlying action happened. */
+    occurredAt: string;
+    /**
+     * Stable id for cross-channel deduplication against the browser pixel (Meta
+     * `event_id`). For `purchase` the host sets it to the order id so the pixel
+     * and the server event collapse into one.
+     */
+    eventId?: string | null;
+    /** Where the action happened — Meta `action_source`. Defaults to `website`. */
+    actionSource?: AnalyticsActionSource;
+    /**
+     * Pseudonymous client identity for sessionization (maps to GA4 `client_id`
+     * / Meta `external_id`). Null when the host cannot resolve a stable id.
+     */
+    clientId?: string | null;
+    sessionId?: string | null;
+    /** Hashed identity + client signals + click ids. See {@link AnalyticsUserData}. */
+    user?: AnalyticsUserData;
+    /** Monetary value for value-bearing events (purchase, begin_checkout). */
+    value?: AnalyticsMoney | null;
+    /** Order id for `purchase` — providers dedupe transactions on it. */
+    transactionId?: string | null;
+    items?: AnalyticsItem[];
+    /** Page context for `page_view`. */
+    pageLocation?: string | null;
+    /** Referring URL, when the host knows it. */
+    pageReferrer?: string | null;
+    pageTitle?: string | null;
+    /** Marketing attribution for the session that produced the event. */
+    utm?: AnalyticsUtm;
+    /** Consent signals resolved by the host for this event. */
+    consent?: AnalyticsConsent;
+    /** Extra params forwarded verbatim as custom dimensions. */
+    params?: Record<string, unknown>;
+}
+interface AnalyticsPluginConfig {
+    supportedCapabilities: AnalyticsFeature[];
+    configSchema: PluginConfigField[];
+    /** GLOBAL-scope defaults merged under the tenant DB config by the host. */
+    defaultConfig?: Record<string, unknown>;
+}
+interface AnalyticsStaticConfig {
+    code: string;
+    displayName: string;
+    description: string;
+    iconUrl?: string;
+    supportedCapabilities: AnalyticsFeature[];
+    configSchema: PluginConfigField[];
+}
+interface IAnalyticsPlugin extends IPlugin {
+    readonly name: string;
+    readonly analyticsConfig: AnalyticsPluginConfig;
+    /**
+     * Forward one canonical event to the provider's ingestion API. Stateless: the
+     * tenant's resolved credentials arrive in `ctx.config` on every call.
+     *
+     * @rule BEST-EFFORT — never throw on a transport/provider error. Analytics is
+     *       fire-and-forget and MUST NOT break the domain flow that triggered it.
+     */
+    track(event: AnalyticsEvent, ctx: DispatchContext): Promise<void>;
+    /**
+     * 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;
@@ -864,6 +1033,7 @@ 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>;
+declare function analyticsCapability(impl: IAnalyticsPlugin): Capability<IAnalyticsPlugin>;
 /**
  * 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
@@ -1001,7 +1171,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.0";
+declare const SDK_VERSION = "0.6.2";
 /**
  * True when a plugin built against `pluginSdkVersion` can run on a host that
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -1010,4 +1180,4 @@ declare const SDK_VERSION = "0.6.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 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 };
+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 };

package/dist/index.js

@@ -20,7 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ANALYTICS_PLUGIN_TOKEN: () => ANALYTICS_PLUGIN_TOKEN,
   ActionVariant: () => ActionVariant,
+  AnalyticsFeature: () => AnalyticsFeature,
   BlockType: () => BlockType,
   CapabilityKind: () => CapabilityKind,
   CodFeeType: () => CodFeeType,
@@ -40,6 +42,7 @@ __export(index_exports, {
   StepStatusFrom: () => StepStatusFrom,
   SuppliersFeature: () => SuppliersFeature,
   TransactionStatus: () => TransactionStatus,
+  analyticsCapability: () => analyticsCapability,
   capability: () => capability,
   checkPermissions: () => checkPermissions,
   createPluginConfig: () => createPluginConfig,
@@ -62,6 +65,7 @@ module.exports = __toCommonJS(index_exports);
 var PAYMENT_PLUGIN_TOKEN = "PAYMENT_PLUGINS";
 var SHIPPING_PLUGIN_TOKEN = "SHIPPING_PLUGINS";
 var SUPPLIERS_PLUGIN_TOKEN = "SUPPLIERS_PLUGINS";
+var ANALYTICS_PLUGIN_TOKEN = "ANALYTICS_PLUGINS";
 
 // src/plugin.ts
 var PluginType = /* @__PURE__ */ ((PluginType2) => {
@@ -200,6 +204,13 @@ var SuppliersFeature = /* @__PURE__ */ ((SuppliersFeature2) => {
   return SuppliersFeature2;
 })(SuppliersFeature || {});
 
+// src/analytics.ts
+var AnalyticsFeature = /* @__PURE__ */ ((AnalyticsFeature2) => {
+  AnalyticsFeature2["Ecommerce"] = "ecommerce";
+  AnalyticsFeature2["PageViews"] = "page-views";
+  return AnalyticsFeature2;
+})(AnalyticsFeature || {});
+
 // src/setup-layout.ts
 var import_superstruct2 = require("superstruct");
 var FieldVariant = /* @__PURE__ */ ((FieldVariant2) => {
@@ -485,6 +496,9 @@ function shippingCapability(impl) {
 function suppliersCapability(impl) {
   return { kind: CapabilityKind.Suppliers, impl };
 }
+function analyticsCapability(impl) {
+  return { kind: CapabilityKind.Analytics, impl };
+}
 var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
 function definePlugin(factory) {
   Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
@@ -530,7 +544,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.6.2";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -547,7 +561,9 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ANALYTICS_PLUGIN_TOKEN,
   ActionVariant,
+  AnalyticsFeature,
   BlockType,
   CapabilityKind,
   CodFeeType,
@@ -567,6 +583,7 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   StepStatusFrom,
   SuppliersFeature,
   TransactionStatus,
+  analyticsCapability,
   capability,
   checkPermissions,
   createPluginConfig,

package/dist/index.mjs

@@ -2,6 +2,7 @@
 var PAYMENT_PLUGIN_TOKEN = "PAYMENT_PLUGINS";
 var SHIPPING_PLUGIN_TOKEN = "SHIPPING_PLUGINS";
 var SUPPLIERS_PLUGIN_TOKEN = "SUPPLIERS_PLUGINS";
+var ANALYTICS_PLUGIN_TOKEN = "ANALYTICS_PLUGINS";
 
 // src/plugin.ts
 var PluginType = /* @__PURE__ */ ((PluginType2) => {
@@ -148,6 +149,13 @@ var SuppliersFeature = /* @__PURE__ */ ((SuppliersFeature2) => {
   return SuppliersFeature2;
 })(SuppliersFeature || {});
 
+// src/analytics.ts
+var AnalyticsFeature = /* @__PURE__ */ ((AnalyticsFeature2) => {
+  AnalyticsFeature2["Ecommerce"] = "ecommerce";
+  AnalyticsFeature2["PageViews"] = "page-views";
+  return AnalyticsFeature2;
+})(AnalyticsFeature || {});
+
 // src/setup-layout.ts
 import {
   array,
@@ -446,6 +454,9 @@ function shippingCapability(impl) {
 function suppliersCapability(impl) {
   return { kind: CapabilityKind.Suppliers, impl };
 }
+function analyticsCapability(impl) {
+  return { kind: CapabilityKind.Analytics, impl };
+}
 var PLUGIN_FACTORY_BRAND = /* @__PURE__ */ Symbol.for("vivoa.plugin.factory");
 function definePlugin(factory) {
   Object.defineProperty(factory, PLUGIN_FACTORY_BRAND, {
@@ -491,7 +502,7 @@ function checkPermissions(required, grantedRaw) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.6.2";
 function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   const parse = (v) => {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
@@ -507,7 +518,9 @@ function isSdkCompatible(pluginSdkVersion, hostSdkVersion) {
   return h[1] > p[1] || h[1] === p[1] && h[2] >= p[2];
 }
 export {
+  ANALYTICS_PLUGIN_TOKEN,
   ActionVariant,
+  AnalyticsFeature,
   BlockType,
   CapabilityKind,
   CodFeeType,
@@ -527,6 +540,7 @@ export {
   StepStatusFrom,
   SuppliersFeature,
   TransactionStatus,
+  analyticsCapability,
   capability,
   checkPermissions,
   createPluginConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivoa/plugin-sdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Public contracts for Vivoa plugins (types, DI tokens, config + setup-layout validators)",
   "license": "MIT",
   "author": "Vivoa",
@@ -34,14 +34,6 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean --target node18",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --target node18",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build"
-  },
   "dependencies": {
     "superstruct": "^2.0.2"
   },
@@ -51,9 +43,11 @@
     "typescript": "^5.7.3",
     "vitest": "^2.1.8"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --target node18",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --target node18",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}