@vivoa/plugin-sdk 0.6.5 → 0.6.6

package/dist/host-api-C1VylW5l.d.mts

@@ -0,0 +1,1416 @@
+declare enum FieldType {
+    String = "string",
+    Password = "password",
+    Url = "url",
+    Number = "number",
+    Boolean = "boolean",
+    Select = "select"
+}
+declare enum ConfigScope {
+    Global = "global",
+    Country = "country"
+}
+interface SelectOption {
+    value: string;
+    label: string;
+}
+interface PluginConfigFieldDependency {
+    field: string;
+    value: string[];
+}
+interface PluginConfigField {
+    key: string;
+    label: string;
+    type: FieldType;
+    required: boolean;
+    scopedTo?: ConfigScope;
+    dependsOn?: PluginConfigFieldDependency;
+    placeholder?: string;
+    description?: string;
+    options?: SelectOption[];
+    internal?: boolean;
+    /** Visual group header rendered above the first field of each new group. */
+    group?: string;
+}
+
+declare enum FieldVariant {
+    Text = "text",
+    Secret = "secret",
+    Url = "url",
+    Number = "number",
+    Select = "select",
+    Textarea = "textarea",
+    /**
+     * Renders a small option set (a `select`-typed schema field) as a segmented
+     * pill control instead of a dropdown. Purely presentational — the underlying
+     * value/options come from the referenced configSchema field.
+     */
+    Segmented = "segmented"
+}
+declare enum ActionVariant {
+    Primary = "primary",
+    Secondary = "secondary",
+    Danger = "danger"
+}
+declare enum RepeaterSource {
+    SupportedCountries = "supportedCountries"
+}
+/**
+ * Presentation mode for the whole layout. Declared by the plugin wins; when
+ * absent the HOST infers it (wizard when the layout iterates per-country,
+ * stacked otherwise). Inference is a host concern and is NOT part of this
+ * contract — the SDK only carries the optional declared value.
+ */
+declare enum LayoutMode {
+    Wizard = "wizard",
+    Stacked = "stacked",
+    Tabs = "tabs",
+    Sections = "sections"
+}
+declare enum BlockType {
+    Field = "field",
+    Group = "group",
+    Toggle = "toggle",
+    Action = "action",
+    Callout = "callout",
+    Markdown = "markdown",
+    Divider = "divider",
+    Conditional = "conditional",
+    Repeater = "repeater",
+    Card = "card",
+    Banner = "banner",
+    CopyField = "copyField",
+    InlineRow = "inlineRow",
+    Tabs = "tabs",
+    Accordion = "accordion",
+    KeyValue = "keyValue"
+}
+declare enum StepStatusFrom {
+    Fields = "fields",
+    Action = "action"
+}
+/**
+ * Shared base every block extends. Carries the optional 12-col grid span
+ * (1–12). Out-of-range values are clamped by the HOST at render time; the
+ * contract accepts any number so a newer plugin is never bricked by an older
+ * host.
+ */
+interface BlockBase {
+    span?: number;
+}
+interface FieldBlock extends BlockBase {
+    type: BlockType.Field;
+    /** References a key in the plugin's configSchema. */
+    key: string;
+    variant?: FieldVariant;
+    /** Override the configSchema label inside this layout. */
+    labelOverride?: string;
+    /**
+     * Name of a `resolveOptions` source. When set, the host resolves the option
+     * list at runtime via `plugin.resolveOptions(optionsFrom, ctx)` instead of a
+     * static option set. NOT a configSchema key — it is a runtime source id.
+     */
+    optionsFrom?: string;
+}
+interface GroupBlock extends BlockBase {
+    type: BlockType.Group;
+    title: string;
+    description?: string;
+    /** configSchema keys included in this group. */
+    fields: string[];
+    collapsible?: boolean;
+    defaultOpen?: boolean;
+}
+interface ToggleBlock extends BlockBase {
+    type: BlockType.Toggle;
+    /** Logical id, not necessarily a config key. */
+    key: string;
+    label: string;
+    description?: string;
+}
+interface ActionBlock extends BlockBase {
+    type: BlockType.Action;
+    /** Matches a manifest.actions[id]. */
+    id: string;
+    label: string;
+    variant?: ActionVariant;
+    /** When set, the action result feeds the named callout slot. */
+    resultSlot?: string;
+}
+interface CalloutBlock extends BlockBase {
+    type: BlockType.Callout;
+    variant: MessageVariant;
+    text: string;
+    /** Slot id for `action.resultSlot` to write into. */
+    slot?: string;
+}
+interface MarkdownBlock extends BlockBase {
+    type: BlockType.Markdown;
+    content: string;
+}
+interface DividerBlock extends BlockBase {
+    type: BlockType.Divider;
+}
+type ConditionalEquals = string | number | boolean | null;
+interface ConditionalWhen {
+    key: string;
+    equals: ConditionalEquals;
+}
+interface ConditionalBlock extends BlockBase {
+    type: BlockType.Conditional;
+    when: ConditionalWhen;
+    blocks: Block[];
+}
+interface RepeaterBlock extends BlockBase {
+    type: BlockType.Repeater;
+    source: RepeaterSource;
+    /** Token interpolation: {countryCode}, {countryName}. */
+    blocks: Block[];
+}
+/** Titled container. Recurses into `blocks`. */
+interface CardBlock extends BlockBase {
+    type: BlockType.Card;
+    title?: string;
+    description?: string;
+    blocks: Block[];
+}
+/** Prominent variant-styled message. Leaf. */
+interface BannerBlock extends BlockBase {
+    type: BlockType.Banner;
+    variant: MessageVariant;
+    title?: string;
+    text: string;
+}
+/**
+ * Read-only value with a copy affordance. EXACTLY ONE source of the value:
+ * a literal, a host `computedValues` key, or a read-only echo of a config key.
+ */
+interface CopyFieldBlock extends BlockBase {
+    type: BlockType.CopyField;
+    label: string;
+    /** Literal value. */
+    value?: string;
+    /** Key into the host-provided `computedValues` map. */
+    computedKey?: string;
+    /** Read-only echo of a configSchema field value. */
+    fieldKey?: string;
+}
+/** Horizontal row on wide viewports, stacks on narrow. Recurses. */
+interface InlineRowBlock extends BlockBase {
+    type: BlockType.InlineRow;
+    blocks: Block[];
+}
+interface TabItem {
+    id: string;
+    label: string;
+    blocks: Block[];
+}
+/** One panel visible at a time. Recurses per tab. */
+interface TabsBlock extends BlockBase {
+    type: BlockType.Tabs;
+    tabs: TabItem[];
+}
+interface AccordionSection {
+    id: string;
+    title: string;
+    defaultOpen?: boolean;
+    blocks: Block[];
+}
+/** Collapsible sections. Local toggle, not persisted. Recurses per section. */
+interface AccordionBlock extends BlockBase {
+    type: BlockType.Accordion;
+    sections: AccordionSection[];
+}
+interface KeyValueRow {
+    label: string;
+    value?: string;
+    computedKey?: string;
+}
+/** Read-only label/value list. Leaf. */
+interface KeyValueBlock extends BlockBase {
+    type: BlockType.KeyValue;
+    rows: KeyValueRow[];
+}
+type Block = FieldBlock | GroupBlock | ToggleBlock | ActionBlock | CalloutBlock | MarkdownBlock | DividerBlock | ConditionalBlock | RepeaterBlock | CardBlock | BannerBlock | CopyFieldBlock | InlineRowBlock | TabsBlock | AccordionBlock | KeyValueBlock;
+interface StepStatusFromFields {
+    from: StepStatusFrom.Fields;
+}
+interface StepStatusFromAction {
+    from: StepStatusFrom.Action;
+    actionId: string;
+}
+type StepStatusSource = StepStatusFromFields | StepStatusFromAction;
+interface SetupStep {
+    id: string;
+    title: string;
+    intro?: string;
+    blocks: Block[];
+    /** When set, the step renders once per item of the source. */
+    repeatFor?: RepeaterSource;
+    status?: StepStatusSource;
+}
+interface SetupAction {
+    id: string;
+    /** Optional human label (admin can render in audit logs). */
+    label?: string;
+    /** Whether the action runs per-country. Default: false. */
+    perCountry?: boolean;
+}
+interface SetupLayout {
+    /** Reserved for Phase 2 — points to a plugin-shipped React bundle. */
+    customScreen?: string;
+    /**
+     * Presentation mode. Declared wins; when absent the host infers it. Additive
+     * in 0.4.0 — an older host ignores it and keeps its inferred layout.
+     */
+    mode?: LayoutMode;
+    intro?: string;
+    steps: SetupStep[];
+    actions?: SetupAction[];
+}
+
+interface SetupLayoutValidation {
+    success: boolean;
+    data?: SetupLayout;
+    errors?: string[];
+}
+/** Validates the full layout including recursive blocks. */
+declare function validateSetupLayout(input: unknown): SetupLayoutValidation;
+declare function crossValidateSetupLayout(layout: SetupLayout, configSchema: PluginConfigField[]): string[];
+
+/**
+ * Verified authorship. `handle` is a stable slug the registry owns — NOT a
+ * display label. Two plugins from the same author share one handle; the host
+ * ties it to the publish token so a third party cannot push versions of a
+ * plugin they do not own. `displayName`/`url` are presentation only.
+ */
+interface PluginAuthor {
+    /** Stable registry identity. Lowercase slug, bound to the publish token. */
+    handle: string;
+    /** Human-facing name shown in the admin app store. */
+    displayName: string;
+    /** Optional author/developer homepage. */
+    url?: string;
+}
+/** A handle is a URL-safe slug: starts alphanumeric, then alphanumerics/dashes. */
+declare const AUTHOR_HANDLE_RE: RegExp;
+interface AuthorValidation {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Pure structural check the REGISTRY runs at publish time (the SDK ships the
+ * rule so host and tooling agree on one spelling). Fail-closed: a missing or
+ * malformed author is rejected, never defaulted.
+ */
+declare function validatePluginAuthor(value: unknown): AuthorValidation;
+
+interface PluginManifest {
+    name: string;
+    displayName?: string;
+    version: string;
+    entry: string;
+    type?: PluginType;
+    icon?: string;
+    description?: string;
+    dependencies?: string[];
+    /** Minimum @vivoa/store host version this plugin runs on (semver). */
+    minHostVersion?: string;
+    /**
+     * SDK contract version the plugin was compiled against (see SDK_VERSION).
+     * Hosts refuse plugins with an incompatible contract via isSdkCompatible.
+     */
+    sdkVersion?: string;
+    /**
+     * Verified authorship. The registry binds `author.handle` to the publish
+     * token on first publish and rejects later versions from a non-owner.
+     * Optional in the TYPE (older manifests predate it); the registry enforces
+     * presence at publish via validatePluginAuthor. Supersedes the free-text
+     * `developer` string first-party manifests used to carry.
+     */
+    author?: PluginAuthor;
+    /**
+     * Declarative admin setup screen. When omitted, host renders the legacy
+     * auto-form derived from the plugin's configSchema.
+     */
+    setup?: SetupLayout;
+}
+
+declare enum PluginType {
+    Payment = "payment",
+    Shipping = "shipping",
+    Analytics = "analytics",
+    Invoicing = "invoicing",
+    Generic = "generic"
+}
+/** Visual tone for messages, callouts and action results. */
+declare enum MessageVariant {
+    Info = "info",
+    Warning = "warning",
+    Success = "success",
+    Danger = "danger"
+}
+interface PluginActionResult {
+    ok: boolean;
+    message?: string;
+    variant?: MessageVariant;
+    data?: unknown;
+}
+interface PluginActionContext {
+    /** When the action was triggered from a country-scoped step. */
+    country?: string;
+    /** Free-form payload sent from the admin UI. */
+    payload?: unknown;
+    /**
+     * Resolved GLOBAL-scope config for the current tenant. The host populates
+     * this so actions (e.g. testConnection) can build a client without any
+     * prior `initialize()` — same stateless discipline as the dispatch methods.
+     */
+    config?: Record<string, unknown>;
+    /** Resolved config for `country`, when the action is country-scoped. */
+    countryConfig?: Record<string, unknown>;
+}
+/** Option resolved at runtime for a field whose `optionsFrom` is set. */
+interface FieldOption {
+    value: string;
+    label: string;
+}
+interface IPlugin {
+    readonly manifest: PluginManifest;
+    onActivate?(): Promise<void>;
+    onDeactivate?(): Promise<void>;
+    invokeAction?(actionId: string, ctx: PluginActionContext): Promise<PluginActionResult>;
+    /**
+     * Resolve the option list for a field whose `optionsFrom` matches `source`.
+     * PURE (query semantics) — the host never persists anything as a side effect
+     * of calling it. Optional: a plugin without it degrades the field to a plain
+     * input. Draft-aware via `ctx` (same resolved-config discipline as
+     * `invokeAction`).
+     */
+    resolveOptions?(source: string, ctx: PluginActionContext): Promise<FieldOption[]>;
+}
+interface ConfigurablePlugin {
+    loadConfig(config: Record<string, unknown>): void;
+}
+declare function isConfigurablePlugin(plugin: unknown): plugin is ConfigurablePlugin;
+
+/**
+ * Everything a plugin needs to serve ONE operation for ONE tenant, resolved by
+ * the host up front. Nothing here is cached on the plugin instance — the same
+ * plugin object serves every tenant, and each call carries its own context.
+ * This is what removes the "init + dispatch in the same synchronous block"
+ * hazard the stateful contract used to require.
+ */
+interface DispatchContext {
+    /** Resolved, merged GLOBAL-scope config for the current tenant. */
+    readonly config: Record<string, unknown>;
+    /**
+     * Resolved config for the country in scope, when the operation is
+     * country-bound (e.g. a shipping quote for SV). Merged defaults + tenant DB.
+     */
+    readonly countryConfig?: Record<string, unknown>;
+    /**
+     * All resolved country configs keyed by ISO code, for operations that span
+     * countries. Prefer {@link countryConfig} for single-country dispatch.
+     */
+    readonly countryConfigs?: Record<string, Record<string, unknown>>;
+    /** The ISO country code in scope, when applicable. */
+    readonly countryCode?: string;
+}
+
+/**
+ * Free-form gateway code defined by each plugin in its manifest/config.
+ * The host stores this string verbatim; no enum of allowed providers.
+ */
+type PaymentGatewayCode = string;
+declare enum TransactionStatus {
+    Pending = "Pending",
+    PendingRedirect = "Pending_Redirect",
+    Approved = "Approved",
+    Declined = "Declined",
+    Failed = "Failed",
+    Error = "Error"
+}
+declare enum GatewayEnvironment {
+    Sandbox = "sandbox",
+    Production = "production"
+}
+interface PaymentCard {
+    number: string;
+    cvv: string;
+    expirationMonth: string;
+    expirationYear: string;
+    holderFirstName: string;
+    holderLastName: string;
+}
+interface PaymentCustomer {
+    email: string;
+    phone: string;
+    address?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    zip?: string;
+}
+interface PaymentPayload {
+    amount: number;
+    currency: string;
+    orderId: string;
+    card: PaymentCard;
+    customer: PaymentCustomer;
+}
+/**
+ * Generic verify payload. Provider-specific data travels in `providerData`,
+ * each plugin casts it to its own type. The host passes it through opaquely.
+ */
+interface PaymentVerifyPayload {
+    transactionId: string;
+    providerData?: unknown;
+}
+interface PaymentResult {
+    status: TransactionStatus;
+    gatewayTransactionId: string;
+    message: string;
+    authorizationCode?: string;
+    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;
+    description: string;
+    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[];
+}
+interface WebhookSignatureResult {
+    isValid: boolean;
+    error?: string;
+}
+interface IPaymentPlugin extends IPlugin {
+    readonly gatewayCode: PaymentGatewayCode;
+    readonly staticConfig: GatewayStaticConfig;
+    readonly paymentConfig?: PaymentPluginConfig;
+    processPayment(payload: PaymentPayload, ctx: DispatchContext): Promise<PaymentResult>;
+    verifyTransaction?(payload: PaymentVerifyPayload, ctx: DispatchContext): Promise<PaymentResult>;
+    validateWebhookSignature?(rawBody: string | Buffer, headers: Record<string, string>, ctx: DispatchContext): WebhookSignatureResult;
+    processWebhook?(payload: unknown, ctx: DispatchContext): Promise<void>;
+    /**
+     * Query the gateway for the current status of a previously attempted charge.
+     * Called by the host when `processPayment` returns `status: Error` with a
+     * non-empty `gatewayTransactionId` (e.g. Serfinsa `audit_no` on timeout).
+     * MUST NOT accept or re-use card data — ID-only reconciliation.
+     */
+    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 {
+    Tracking = "tracking",
+    Cod = "cod",
+    Quotes = "quotes",
+    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",
+    Fixed = "fixed"
+}
+interface CodFeeConfig {
+    type: CodFeeType;
+    value: number;
+    description: string;
+}
+interface ShippingDefaultConfig {
+    global?: Record<string, unknown>;
+    countries?: Record<string, Record<string, unknown>>;
+}
+interface ShippingPluginConfig {
+    supportedCountries: string[];
+    supportedFeatures: ShippingFeature[];
+    configSchema: PluginConfigField[];
+    codFeeConfig?: CodFeeConfig;
+    defaultConfig?: ShippingDefaultConfig;
+}
+interface ShippingStaticConfig {
+    code: string;
+    displayName: string;
+    description: string;
+    iconUrl?: string;
+    supportedCountries: string[];
+    supportedFeatures: ShippingFeature[];
+    configSchema: PluginConfigField[];
+    codFeeConfig?: CodFeeConfig;
+}
+interface ShipmentAddress {
+    fullName: string;
+    phone: string;
+    phoneAreaCode: string;
+    email: string | null;
+    address: string;
+    referencePoint: string;
+    instructions?: string;
+    city: string;
+    cityId?: string;
+    state: string;
+    stateId?: string;
+    zip?: string;
+    country: string;
+    latitude?: number;
+    longitude?: number;
+}
+interface ShipmentParcel {
+    content: string;
+    length: number;
+    width: number;
+    height: number;
+    weight: number;
+    price?: number;
+    isFragile?: boolean;
+}
+interface ShippingQuoteParams {
+    origin: ShipmentAddress;
+    destination: ShipmentAddress;
+    countryCode: string;
+    parcels?: ShipmentParcel[];
+}
+interface ShippingQuote {
+    carrierId: string;
+    carrierName: string;
+    price: number;
+    codCommission: number;
+    codFee?: number;
+    supportsCod: boolean;
+    deliveryType: string;
+    logo: string | null;
+    isPricePromotion: boolean;
+    isCommissionPromotion: boolean;
+    provider: string;
+}
+interface CodConfig {
+    enabled: boolean;
+    amount: number;
+}
+interface CreateShipmentParams {
+    orderId: string;
+    pickup: ShipmentAddress;
+    delivery: ShipmentAddress;
+    parcels: ShipmentParcel[];
+    recolectionDate: Date;
+    cod?: CodConfig;
+    courierId?: string;
+    serviceLevelToken?: string;
+}
+interface ShipmentResult {
+    externalId: string;
+    trackingNumber: string;
+    trackingUrl: string;
+    labelUrl: string | null;
+    provider: string;
+    courierName: string;
+    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;
+    createShipment(params: CreateShipmentParams, ctx: DispatchContext): Promise<ShipmentResult>;
+    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-native geo ids. Optional: when the host cannot produce the
+     * supplier's own ids (the common case — the host only knows its own geo),
+     * it leaves these empty and passes the human-readable names below. The
+     * plugin resolves names → supplier ids against its own geo endpoints.
+     */
+    stateId?: string;
+    cityId?: string;
+    /** ISO 3166-1 alpha-2 of the destination country (e.g. "GT", "SV"). */
+    countryCode?: string;
+    /** Human-readable admin-area (state/department) name for plugin-side resolution. */
+    stateName?: string;
+    /** Human-readable locality (city/municipality) name for plugin-side resolution. */
+    cityName?: 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>;
+    cancelOrder?(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;
+}
+
+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;
+}
+
+declare enum InvoicingFeature {
+    /** Emit a fiscal document against the authority. */
+    Issue = "issue",
+    /** Invalidate / annul a previously issued document. */
+    Void = "void",
+    /** Query the current authority status of an issued document. */
+    StatusQuery = "status-query",
+    /** Retrieve the rendered PDF of an issued document. */
+    Pdf = "pdf"
+}
+/**
+ * Generic fiscal document types. The adapter maps each to its national catalog
+ * (e.g. SV MH: Invoice→Factura Consumidor Final "01", CreditInvoice→Comprobante
+ * de Crédito Fiscal "03", ExcludedSubject→Factura Sujeto Excluido "14", ...).
+ */
+declare enum InvoiceDocumentType {
+    /** Final-consumer invoice. */
+    Invoice = "invoice",
+    /** Tax-credit document for registered taxpayers (SV CCF). */
+    CreditInvoice = "credit-invoice",
+    /** Credit note against a prior document. */
+    CreditNote = "credit-note",
+    /** Debit note against a prior document. */
+    DebitNote = "debit-note",
+    /** Document for suppliers not registered as taxpayers (SV Sujeto Excluido). */
+    ExcludedSubject = "excluded-subject",
+    /** Export invoice. */
+    Export = "export"
+}
+/**
+ * Authority status of an issued document. `unknown` is a first-class value for
+ * provider states the adapter does not map — the host treats it as "not yet
+ * resolved" instead of guessing.
+ */
+declare enum InvoiceStatus {
+    /** Submitted, awaiting the authority's acceptance. */
+    Pending = "pending",
+    /** Accepted and sealed by the authority. */
+    Accepted = "accepted",
+    /** Rejected by the authority (see statusDescription for the reason). */
+    Rejected = "rejected",
+    /** Previously accepted, later invalidated/annulled. */
+    Voided = "voided",
+    Unknown = "unknown"
+}
+/**
+ * ISO-4217 money in minor units — mirrors the store's Money VO so the host maps
+ * 1:1 without a currency guess. Kept local so the SDK stays dependency-free.
+ */
+interface InvoiceMoney {
+    amountMinor: number;
+    currency: string;
+}
+/**
+ * A party to the document (issuer or recipient). Fields are generic; the adapter
+ * maps `taxId` to the national identifier it needs (NIT/NRC/DUI in SV, RFC in
+ * MX). Most are optional because a final-consumer invoice needs far less than a
+ * tax-credit document.
+ */
+interface InvoiceParty {
+    /** Legal / trade name of the party. */
+    name: string;
+    /** National tax identifier (SV NIT, MX RFC, ...). */
+    taxId?: string | null;
+    /** Secondary fiscal registry id where the country splits them (SV NRC). */
+    taxRegistryId?: string | null;
+    /** Personal id when the party is a natural person (SV DUI). */
+    personalId?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    address?: string | null;
+    city?: string | null;
+    state?: string | null;
+    country?: string | null;
+    /** Economic-activity code where the authority requires it. */
+    activityCode?: string | null;
+    activityDescription?: string | null;
+}
+/** A tax applied to a line or to the whole document. */
+interface InvoiceTax {
+    /** Generic code (adapter maps to the national tax code, e.g. SV IVA "20"). */
+    code: string;
+    description?: string;
+    /** Rate as a fraction (0.13 for 13% IVA), when the tax is rate-based. */
+    rate?: number;
+    amount: InvoiceMoney;
+}
+/** A single line item of the document. */
+interface InvoiceLine {
+    /** Store product id, for traceability back to the catalog. */
+    productId?: string | null;
+    variantId?: string | null;
+    sku?: string | null;
+    description: string;
+    quantity: number;
+    /** Unit of measure code where the authority requires it. */
+    unitCode?: string | null;
+    unitPrice: InvoiceMoney;
+    /** Line discount, when any. */
+    discount?: InvoiceMoney;
+    /** Line subtotal (quantity * unitPrice - discount), before document taxes. */
+    subtotal: InvoiceMoney;
+    /** Per-line taxes, when the country computes tax at the line level. */
+    taxes?: InvoiceTax[];
+}
+/**
+ * The host builds this from an Order (or a manual admin action) and hands it to
+ * the adapter. Fiscal identifiers are NOT part of the request — the provider
+ * assigns them and returns them on {@link InvoiceResult}.
+ */
+interface InvoiceRequest {
+    /** Store order id, used by the adapter as the idempotency key. */
+    orderId: string;
+    documentType: InvoiceDocumentType;
+    /** ISO-4217 currency of the whole document. */
+    currency: string;
+    /** The seller — defaults to the store's fiscal identity when omitted by host. */
+    issuer?: InvoiceParty;
+    /** The buyer. */
+    recipient: InvoiceParty;
+    lines: InvoiceLine[];
+    /** Document-level taxes (when the country totals tax at the document level). */
+    taxes?: InvoiceTax[];
+    /** Sum of line subtotals before taxes. */
+    subtotal: InvoiceMoney;
+    /** Total taxes applied. */
+    taxTotal?: InvoiceMoney;
+    /** Grand total the customer pays. */
+    total: InvoiceMoney;
+    /** ISO-8601 instant the sale happened. */
+    issuedAt?: string;
+    /** Free-form notes to print on the document. */
+    notes?: string;
+    /** Provider-specific extras the host cannot model generically. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Outcome of an issue / void / query. The fiscal identifiers are provider output
+ * — all optional because a Rejected result may carry none of them. `status`
+ * drives the host's control flow; `rawResponse` is for diagnostics only.
+ */
+interface InvoiceResult {
+    status: InvoiceStatus;
+    /** Authority generation code / UUID (SV "Código de Generación"). */
+    generationCode?: string | null;
+    /** Control number assigned to the document (SV "Número de Control"). */
+    controlNumber?: string | null;
+    /** Authority reception seal confirming validity (SV "Sello de Recepción"). */
+    receptionSeal?: string | null;
+    /** URL to the rendered PDF, when the provider exposes one. */
+    pdfUrl?: string | null;
+    /** URL to the signed JSON artifact, when the provider exposes one. */
+    jsonUrl?: string | null;
+    /** Human-readable authority/provider status, for audit/logging. */
+    statusDescription?: string;
+    /** Untouched provider payload, for diagnostics. Never trusted for control flow. */
+    rawResponse?: Record<string, unknown>;
+}
+/** Input to invalidate a previously issued document. */
+interface VoidInvoiceInput {
+    /** The generation code of the document to invalidate. */
+    generationCode: string;
+    /** Reason for the invalidation, required by most authorities. */
+    reason: string;
+}
+interface InvoicingDefaultConfig {
+    global?: Record<string, unknown>;
+    countries?: Record<string, Record<string, unknown>>;
+}
+interface InvoicingPluginConfig {
+    supportedCountries: string[];
+    supportedFeatures: InvoicingFeature[];
+    supportedDocumentTypes: InvoiceDocumentType[];
+    configSchema: PluginConfigField[];
+    /** GLOBAL + per-country defaults merged under the tenant DB config by the host. */
+    defaultConfig?: InvoicingDefaultConfig;
+}
+interface InvoicingStaticConfig {
+    code: string;
+    displayName: string;
+    description: string;
+    iconUrl?: string;
+    supportedCountries: string[];
+    supportedFeatures: InvoicingFeature[];
+    supportedDocumentTypes: InvoiceDocumentType[];
+    configSchema: PluginConfigField[];
+}
+interface IInvoicingPlugin extends IPlugin {
+    readonly name: string;
+    readonly invoicingConfig: InvoicingPluginConfig;
+    /**
+     * Emit a fiscal document against the authority. Stateless: the tenant's
+     * resolved credentials arrive in `ctx.config` on every call. The adapter uses
+     * `req.orderId` as the idempotency key so a retry never double-issues.
+     */
+    issueInvoice(req: InvoiceRequest, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Invalidate a previously issued document.
+     * @compat Only plugins advertising the {@link InvoicingFeature.Void} feature.
+     */
+    voidInvoice?(input: VoidInvoiceInput, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Query the authority's current status of an issued document.
+     * @compat Only plugins advertising the {@link InvoicingFeature.StatusQuery} feature.
+     */
+    queryStatus?(ref: {
+        generationCode: string;
+    }, ctx: DispatchContext): Promise<InvoiceResult>;
+    /**
+     * Optional readiness probe. Availability = enabled AND isConfigured.
+     * @compat When omitted, the host assumes the adapter is ready.
+     */
+    isConfigured?(ctx: DispatchContext): boolean;
+}
+
+/** A named unit of behaviour a plugin exposes to the host registry. */
+interface Capability<T = unknown> {
+    kind: string;
+    impl: T;
+}
+/**
+ * Canonical built-in capability kinds. Open set — a plugin MAY register a
+ * `kind` not listed here; the host routes by string. These constants exist so
+ * first-party contracts share one spelling.
+ */
+declare const CapabilityKind: {
+    readonly Payment: "payment";
+    readonly Shipping: "shipping";
+    readonly Suppliers: "suppliers";
+    readonly Analytics: "analytics";
+    readonly Invoicing: "invoicing";
+};
+type CapabilityKind = (typeof CapabilityKind)[keyof typeof CapabilityKind];
+declare function capability<T>(kind: string, impl: T): Capability<T>;
+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>;
+declare function invoicingCapability(impl: IInvoicingPlugin): Capability<IInvoicingPlugin>;
+/**
+ * A constructed plugin. `capabilities` is the static declaration the host reads
+ * up front; `onActivate` runs when the host mounts the plugin for a tenant and
+ * is where side-effecting registration/subscription happens.
+ */
+interface Plugin {
+    readonly manifest: PluginManifest;
+    readonly capabilities: Capability[];
+    onActivate?(host: HostApi): void | Promise<void>;
+    onDeactivate?(): void | Promise<void>;
+}
+/**
+ * The plugin entry point. The compiled bundle's default export is a
+ * `PluginFactory`; the host calls it with a per-tenant `HostApi`. No NestJS,
+ * no decorators — the host owns dependency injection on its side.
+ */
+type PluginFactory = (host: HostApi) => Plugin | Promise<Plugin>;
+/**
+ * Anchors the factory type for plugin authors AND brands the function so the
+ * host loader can tell a `PluginFactory` (new, framework-agnostic) apart from a
+ * legacy NestJS `@Module` default export at runtime.
+ */
+declare function definePlugin(factory: PluginFactory): PluginFactory;
+/** True when `value` was produced by {@link definePlugin}. */
+declare function isPluginFactory(value: unknown): value is PluginFactory;
+
+interface Logger {
+    debug(message: string, ...meta: unknown[]): void;
+    info(message: string, ...meta: unknown[]): void;
+    warn(message: string, ...meta: unknown[]): void;
+    error(message: string, ...meta: unknown[]): void;
+}
+interface HttpRequest {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+/**
+ * Outbound HTTP mediated by the host. The host enforces the plugin's
+ * `http.outbound:<host>` permissions before the request leaves the process —
+ * the plugin cannot reach the network directly.
+ */
+interface HttpClient {
+    request(req: HttpRequest): Promise<HttpResponse>;
+}
+/**
+ * Secret access mediated by the host (never `process.env` directly). Gated by
+ * `secrets.read:<key>` permissions. Returns the resolved per-tenant secret.
+ */
+interface SecretStore {
+    get(key: string): Promise<string | undefined>;
+}
+/** Object storage mediated by the host (presigned broker under the hood). */
+interface StorageBroker {
+    getUrl(key: string): Promise<string>;
+    put(key: string, body: Uint8Array | string): Promise<void>;
+}
+/**
+ * Monotonic sequence numbers owned and PERSISTED by the host. A stateless
+ * plugin cannot keep its own counter (it holds no per-tenant state and the same
+ * object serves every tenant), yet some gateways require a strictly increasing,
+ * unique-per-merchant number (e.g. Serfinsa's `audit_no`). The plugin asks the
+ * host for the next value under a plugin-chosen `scope` string; the host does
+ * the atomic increment and durable storage.
+ *
+ * `scope` namespaces the counter — encode everything that must have its own run
+ * of numbers, e.g. `serfinsa:audit_no:<merchantId>`. Two calls with the same
+ * scope never return the same value; different scopes are independent.
+ */
+interface SequenceStore {
+    next(scope: string): Promise<number>;
+}
+type DomainEventName = string;
+type DomainEventHandler = (payload: unknown) => void | Promise<void>;
+/**
+ * The one object a plugin factory receives. It is the plugin's ENTIRE window
+ * into the host — no `@nestjs/*`, no prisma, no `process`. Everything the
+ * plugin can do flows through these ports, which lets the host enforce the
+ * plugin's declared permissions and swap the transport (in-process today,
+ * worker/WASM later) without touching plugin code.
+ */
+interface HostApi {
+    readonly logger: Logger;
+    readonly http: HttpClient;
+    readonly secrets: SecretStore;
+    readonly storage: StorageBroker;
+    readonly sequence: SequenceStore;
+    /** Subscribe to a host domain event (order.created, product.updated, ...). */
+    on(event: DomainEventName, handler: DomainEventHandler): void;
+    /** Expose a capability to the host's generic registry. */
+    registerCapability<T = unknown>(cap: Capability<T>): void;
+}
+
+export { type IAnalyticsPlugin as $, AUTHOR_HANDLE_RE as A, type BannerBlock as B, ConfigScope as C, type ConditionalBlock as D, type ConditionalEquals as E, FieldType as F, type ConditionalWhen as G, type ConfigurablePlugin as H, type CopyFieldBlock as I, type CreateShipmentParams as J, type DispatchContext as K, type DividerBlock as L, type DomainEventHandler as M, type DomainEventName as N, type EmbedInit as O, type PluginConfigField as P, type FieldBlock as Q, type FieldOption as R, type SelectOption as S, FieldVariant as T, GatewayEnvironment as U, type GatewayStaticConfig as V, type GroupBlock as W, type HostApi as X, type HttpClient as Y, type HttpRequest as Z, type HttpResponse as _, type AccordionBlock as a, type StepStatusSource as a$, type IInvoicingPlugin as a0, type IPaymentPlugin as a1, type IPlugin as a2, type IShippingPlugin as a3, type ISuppliersPlugin as a4, type InlineRowBlock as a5, InvoiceDocumentType as a6, type InvoiceLine as a7, type InvoiceMoney as a8, type InvoiceParty as a9, type PluginActionContext as aA, type PluginActionResult as aB, type PluginAuthor as aC, type PluginConfigFieldDependency as aD, type PluginFactory as aE, type PluginManifest as aF, PluginType as aG, type RepeaterBlock as aH, RepeaterSource as aI, type SecretStore as aJ, type SequenceStore as aK, type SetupAction as aL, type SetupLayout as aM, type SetupLayoutValidation as aN, type SetupStep as aO, type ShipmentAddress as aP, type ShipmentParcel as aQ, type ShipmentResult as aR, type ShippingDefaultConfig as aS, ShippingFeature as aT, type ShippingPluginConfig as aU, type ShippingQuote as aV, type ShippingQuoteParams as aW, type ShippingStaticConfig as aX, StepStatusFrom as aY, type StepStatusFromAction as aZ, type StepStatusFromFields as a_, type InvoiceRequest as aa, type InvoiceResult as ab, InvoiceStatus as ac, type InvoiceTax as ad, type InvoicingDefaultConfig as ae, InvoicingFeature as af, type InvoicingPluginConfig as ag, type InvoicingStaticConfig as ah, type KeyValueBlock as ai, type KeyValueRow as aj, LayoutMode as ak, type Logger as al, type MarkdownBlock as am, MessageVariant as an, type PaymentCard as ao, type PaymentCustomer as ap, type PaymentGatewayCode as aq, type PaymentPayload as ar, type PaymentPluginConfig as as, type PaymentRenderMode as at, type PaymentResult as au, type PaymentSessionPayload as av, type PaymentSessionResult as aw, type PaymentVerifyPayload as ax, type PlaceSupplierOrderInput as ay, type Plugin as az, type AccordionSection as b, type StorageBroker as b0, type SupplierCatalogQuery as b1, type SupplierFulfillmentEvent as b2, type SupplierListing as b3, type SupplierListingAttribute as b4, type SupplierListingPage as b5, type SupplierListingVariant as b6, type SupplierMoney as b7, type SupplierOrderAddressLevel as b8, type SupplierOrderCustomer as b9, validatePluginAuthor as bA, validateSetupLayout as bB, type SupplierOrderLine as ba, type SupplierOrderResult as bb, type SupplierOrderStatus as bc, type SupplierShipTo as bd, type SupplierStock as be, type SuppliersDefaultConfig as bf, SuppliersFeature as bg, type SuppliersPluginConfig as bh, type SuppliersStaticConfig as bi, type TabItem as bj, type TabsBlock as bk, type ToggleBlock as bl, type TrackingEvent as bm, TransactionStatus as bn, type VoidInvoiceInput as bo, type WebhookSignatureResult as bp, analyticsCapability as bq, capability as br, crossValidateSetupLayout as bs, definePlugin as bt, invoicingCapability as bu, isConfigurablePlugin as bv, isPluginFactory as bw, paymentCapability as bx, shippingCapability as by, suppliersCapability as bz, type ActionBlock as c, ActionVariant as d, type AnalyticsActionSource as e, type AnalyticsConsent as f, type AnalyticsEvent as g, type AnalyticsEventName as h, AnalyticsFeature as i, type AnalyticsItem as j, type AnalyticsMoney as k, type AnalyticsPluginConfig as l, type AnalyticsStaticConfig as m, type AnalyticsUserData as n, type AnalyticsUtm as o, type AuthorValidation as p, type Block as q, type BlockBase as r, BlockType as s, type CalloutBlock as t, type Capability as u, CapabilityKind as v, type CardBlock as w, type CodConfig as x, type CodFeeConfig as y, CodFeeType as z };