@vivoa/plugin-sdk 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,788 @@
+declare const PAYMENT_PLUGIN_TOKEN: "PAYMENT_PLUGINS";
+declare const SHIPPING_PLUGIN_TOKEN: "SHIPPING_PLUGINS";
+
+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[];
+
+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;
+    /**
+     * 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",
+    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;
+
+interface FieldDependsOn {
+    field: string;
+    value: string | string[];
+}
+interface FieldDefinition {
+    label: string;
+    type: FieldType;
+    required?: boolean;
+    scopedTo?: ConfigScope;
+    dependsOn?: FieldDependsOn;
+    placeholder?: string;
+    description?: string;
+    options?: SelectOption[];
+    internal?: boolean;
+    group?: string;
+}
+declare function field(def: FieldDefinition): FieldDefinition;
+type FieldMap = Record<string, FieldDefinition>;
+interface PluginConfigValidation {
+    success: boolean;
+    data?: Record<string, unknown>;
+    errors?: string[];
+}
+interface PluginConfigResult {
+    configFields: PluginConfigField[];
+    validate: (data: unknown) => PluginConfigValidation;
+}
+declare function createPluginConfig(fields: FieldMap): PluginConfigResult;
+
+/**
+ * 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;
+}
+interface GatewayStaticConfig {
+    code: PaymentGatewayCode;
+    displayName: string;
+    description: string;
+    environment: GatewayEnvironment;
+    supportedMethods: string[];
+    requiredEnvVars: 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>;
+}
+
+declare enum ShippingFeature {
+    Tracking = "tracking",
+    Cod = "cod",
+    Quotes = "quotes",
+    Labels = "labels"
+}
+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>;
+}
+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;
+    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 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>;
+/**
+ * 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;
+}
+
+/** Wire format: `domain.action` or `domain.action:resource`. */
+interface Permission {
+    domain: string;
+    action: string;
+    resource?: string;
+}
+declare function parsePermission(raw: string): Permission | null;
+/**
+ * True when `required` is covered by `granted`. Domain+action must match. For
+ * the resource dimension:
+ * - required has no resource  → a granted domain.action (any resource) covers it.
+ * - required has a resource    → needs a granted entry with the same resource,
+ *                                or a wildcard '*' grant. A resource-less grant
+ *                                does NOT cover a resource-scoped requirement.
+ */
+declare function isPermissionGranted(required: Permission, granted: Permission[]): boolean;
+interface PermissionCheck {
+    ok: boolean;
+    granted: string[];
+    missing: string[];
+}
+/**
+ * Splits `required` raw strings into granted vs missing against `grantedRaw`.
+ * Malformed required strings are always reported as missing (fail closed).
+ */
+declare function checkPermissions(required: string[], grantedRaw: string[]): PermissionCheck;
+
+/**
+ * Version of the plugin SDK CONTRACT (kept in sync with package.json by the
+ * release script). Plugins compiled against this SDK declare it in their
+ * manifest (`sdkVersion`); hosts use it to refuse loading plugins built
+ * against an incompatible contract.
+ *
+ * Semver discipline for the contract:
+ * - MAJOR: breaking change to any exported type/token — hosts refuse mismatched majors.
+ * - MINOR: additive (new optional fields, new tokens) — backwards compatible.
+ * - PATCH: docs/fixes with zero shape changes.
+ */
+declare const SDK_VERSION = "0.5.0";
+/**
+ * True when a plugin built against `pluginSdkVersion` can run on a host that
+ * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
+ * Pre-1.0 caveat: majors are 0, so minors act as breaking boundaries — hence
+ * the stricter equality check while major is 0 (npm-style ^0.x semantics).
+ */
+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 };