@endora-commerce/mod-payments 0.100.0

package/dist/backend/services/receive-payment-handler.js

@@ -0,0 +1,356 @@
+import { randomUUID } from 'crypto';
+import { ERROR_CODES, ORDER_STATUS_ON_HOLD } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { Payment } from '../entities/payment.entity.js';
+/**
+ * ReceivePaymentHandler (feature 034, FR-022/FR-023/FR-025).
+ *
+ * Resolves a Payment from the ingress payload, applies the outcome, and asks
+ * the order lifecycle for the move the method's `statusOnSuccess` /
+ * `statusOnFailure` names. Idempotent: a success after a terminal `paid` is a
+ * no-op; a failure after `paid` is rejected (no downgrade). Resolves a late
+ * event even when the adapter has since been de-registered (it keys on the
+ * persisted Payment, not the live registry).
+ *
+ * **The lifecycle answers; this handler does not decide** (feature 085 Phase
+ * D). It used to assign `order.status` after asking an `OrderStatusRegistry`
+ * whether the code existed, which is a different question from whether the
+ * order may go there — so the ingress wrote transitions the configured graph
+ * forbids, on the happy path, while an operator making the same move by hand
+ * was refused. Existence is now the port's `unknown_status` answer and
+ * reachability its `not_permitted` one, and both leave the order where it is.
+ */
+export class ReceivePaymentHandler {
+    emFactory;
+    paymentMethodRead;
+    orderTransition;
+    orderPaymentStatus;
+    log;
+    events;
+    constructor(emFactory, 
+    /**
+     * The method behind the payment, as `payment_methods` publishes it. Read
+     * inside the settlement transaction, as `shipments` reads its delivery
+     * method: it is a read of a row this transaction never writes, so it is not
+     * held by `payments_order_fk` and carries none of the atomicity the `Order`
+     * import above does. When `payment_methods` is off it throws, inside the
+     * transaction, and the payment and the order roll back together.
+     */
+    paymentMethodRead, 
+    /**
+     * The lifecycle write (feature 085 Phase D). It validates against the
+     * configured graph, runs the veto guards, records the audit entry and
+     * applies the status's side-effects — the five things the assignment this
+     * replaced did none of, which is why a payment-driven cancellation used to
+     * leave the order's stock allocated forever and audited nowhere.
+     *
+     * **Called after this handler's transaction has committed**, never inside
+     * it: the port takes its own `EntityManager`, so a call from inside would
+     * write the order on a different pooled connection whose commit the
+     * enclosing rollback cannot reach (issue #200). The port's own doc block
+     * states the obligation.
+     *
+     * It announces the change too — `OrderTransitionService` emits the
+     * templated `order.status.*.after` events itself — so this handler no
+     * longer resolves `orderStatusAnnouncePort`. Doing both would emit every
+     * payment-driven status change twice.
+     */
+    orderTransition, 
+    /**
+     * The money axis of the order this payment settles (feature 080, T048).
+     *
+     * **Called inside this handler's transaction**, unlike `orderTransition`
+     * above, and the asymmetry is the whole reason there are two ports rather
+     * than one: `payments_order_fk` (`on delete restrict`) holds the payment row
+     * and `orders.payment_status` together, so that write may not commit
+     * separately from this one — while a *lifecycle* transition obtains its own
+     * `EntityManager` and may not run inside it. The interface takes the
+     * caller's `EntityManager` as a required parameter for exactly that reason
+     * (D-169), and the header above states the constraint in full.
+     */
+    orderPaymentStatus, 
+    /** Where a refused transition is recorded; see {@link SettlementLogger}. */
+    log, events) {
+        this.emFactory = emFactory;
+        this.paymentMethodRead = paymentMethodRead;
+        this.orderTransition = orderTransition;
+        this.orderPaymentStatus = orderPaymentStatus;
+        this.log = log;
+        this.events = events;
+    }
+    async receive(input) {
+        // command-coverage-ignore: provider payment-event ingestion — stamps the
+        // attempt result on the Payment row and the order's payment status, then
+        // asks `orderTransitionPort` for the lifecycle move, which records the
+        // `order.status_transition` audit entry co-transactionally with the status
+        // write it performs. The reason on this marker used to claim that audit
+        // while the handler assigned `order.status` itself and reached the orders
+        // flow at no point (feature 085, R3); Phase D made the claim true by
+        // routing the move through the seam that carries it.
+        const em = this.emFactory();
+        const result = await em.transactional(async (tx) => {
+            const payment = await this.resolvePayment(tx, input);
+            if (!payment) {
+                throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Payment not found for the given reference.');
+            }
+            // Idempotency / terminal-state guards (FR-025).
+            if (payment.status === 'paid') {
+                if (input.outcome === 'failure') {
+                    throw new HttpError(409, ERROR_CODES.VALIDATION_FAILED, 'Payment is already settled; it cannot be marked failed.');
+                }
+                return {
+                    payment,
+                    orderStatus: null,
+                    idempotent: true,
+                    emit: false,
+                    transition: null,
+                };
+            }
+            const method = await this.paymentMethodRead.findById(payment.paymentMethodId);
+            let transition = null;
+            // The order this settlement moves, written through its owner's
+            // `EntityManager`-taking port on THIS transaction (see the header). It
+            // answers `null` for an order that is not there — the same state the
+            // `if (order)` guards this replaces described — and a published record
+            // otherwise, so the lifecycle status below is read rather than reachable.
+            let applied = null;
+            if (input.outcome === 'success') {
+                payment.status = 'paid';
+                payment.paidAt = new Date();
+                if (input.externalReference !== undefined) {
+                    payment.externalReference = input.externalReference ?? null;
+                }
+                if (input.providerDetails)
+                    payment.providerDetails = input.providerDetails;
+                applied = await this.orderPaymentStatus.applyPaymentStatus(tx, {
+                    orderId: payment.orderId,
+                    paymentStatus: 'paid',
+                });
+                if (method?.statusOnSuccess) {
+                    transition = { to: method.statusOnSuccess, setting: 'status_on_success' };
+                }
+            }
+            else {
+                payment.status = 'failed';
+                payment.failureReason = input.failureReason ?? null;
+                if (input.providerDetails)
+                    payment.providerDetails = input.providerDetails;
+                // Feature 085 (FR-001) — the decline is recorded on the money axis
+                // too. The lifecycle status alone could not say it: the method's
+                // `status_on_failure` is operator-configurable, so two orders sitting
+                // at the same status may have arrived there for opposite reasons, and
+                // the buyer's retry and the operator's list both need to know which.
+                applied = await this.orderPaymentStatus.applyPaymentStatus(tx, {
+                    orderId: payment.orderId,
+                    paymentStatus: 'failed',
+                });
+                if (method?.statusOnFailure) {
+                    transition = { to: method.statusOnFailure, setting: 'status_on_failure' };
+                }
+            }
+            await tx.flush();
+            return {
+                payment,
+                orderStatus: applied?.status ?? null,
+                idempotent: false,
+                emit: true,
+                adapter: method?.adapter ?? payment.paymentMethodId,
+                transition,
+            };
+        });
+        /**
+         * After the commit, never inside the transaction above (feature 085 R4).
+         *
+         * `OrderTransitionService` obtains its own `EntityManager`, so a call from
+         * inside `em.transactional` would write the order on a second pooled
+         * connection that commits on its own — the shape `check:transaction-context`
+         * refuses. The asymmetry of putting it here is deliberate and lands on the
+         * safe side: a crash between the commit and this line leaves the payment
+         * recorded and the lifecycle unmoved, which the buyer retries, where the
+         * opposite ordering would hold an order against a payment nobody recorded.
+         */
+        const orderStatus = result.transition
+            ? await this.moveOrder(result.payment.orderId, result.transition.to, result.transition.setting, result.orderStatus, input.outcome === 'failure' ? (input.failureReason ?? null) : null)
+            : result.orderStatus;
+        if (result.emit && this.events) {
+            const base = { eventId: randomUUID(), occurredAt: new Date().toISOString() };
+            if (result.payment.status === 'paid') {
+                this.events.emit('payment.received.v1', {
+                    ...base,
+                    orderId: result.payment.orderId,
+                    paymentId: result.payment.id,
+                    adapter: result.adapter ?? '',
+                    externalReference: result.payment.externalReference ?? null,
+                    attemptNo: result.payment.attemptNo,
+                });
+            }
+            else {
+                this.events.emit('payment.failed.v1', {
+                    ...base,
+                    orderId: result.payment.orderId,
+                    paymentId: result.payment.id,
+                    adapter: result.adapter ?? '',
+                    failureReason: result.payment.failureReason ?? null,
+                    attemptNo: result.payment.attemptNo,
+                });
+            }
+            // The templated `order.status.*.after` events (feature 038, T026) are no
+            // longer emitted from here: `OrderTransitionService` emits them itself,
+            // for the transition it applied, with the same actor and the order's
+            // business id besides. Announcing again would double every subscriber's
+            // reaction to a payment-driven status change.
+        }
+        return {
+            paymentId: result.payment.id,
+            status: result.payment.status,
+            orderStatus,
+            idempotent: result.idempotent,
+        };
+    }
+    /**
+     * Ask the lifecycle for the move the configured setting names, and answer
+     * where the order ended up.
+     *
+     * Every refusal is a 200 for the provider (contract §"What the caller does
+     * with each outcome"): a PSP retries a non-2xx callback indefinitely, and an
+     * order an operator has already advanced past payment must not be dragged
+     * backwards because a delayed webhook arrived. So the refusal is recorded
+     * here and the settlement stands.
+     *
+     * There is deliberately no `catch`. A `ModuleDisabledError` out of the port's
+     * gate is not a refusal — it is the owner being absent — and swallowing it
+     * would turn fail-closed into fail-open.
+     */
+    async moveOrder(orderId, to, setting, statusBefore, reason) {
+        const outcome = await this.orderTransition.applyStatus({
+            orderId,
+            to,
+            actor: { kind: 'system', source: 'payment' },
+            reason,
+        });
+        if (outcome.applied)
+            return outcome.to;
+        // A second declined attempt on an order already at the failure status: the
+        // attempt is recorded, nothing moved, and nothing needs saying (FR-006).
+        if (outcome.reason === 'already_there')
+            return outcome.from;
+        this.log.warn({
+            orderId,
+            from: outcome.from,
+            to,
+            setting,
+            refusal: outcome.reason,
+            detail: outcome.detail,
+        }, 'payments: the requested order status was not applied; the order keeps the one it has');
+        return outcome.from ?? statusBefore;
+    }
+    /**
+     * Reflect a gateway refund onto the Payment + Order (feature 049). Driven by
+     * the `charge.refunded` webhook for BOTH Dashboard- and platform-initiated
+     * refunds. `refundedAmount` is the gateway's cumulative total, so this is
+     * idempotent by construction (re-applying the same total is a no-op) and never
+     * calls the gateway back (no refund loop). A fully-refunded payment is never
+     * downgraded to partial.
+     */
+    async reflectRefund(input) {
+        const em = this.emFactory();
+        const result = await em.transactional(async (tx) => {
+            const payment = await this.resolvePaymentForRefund(tx, input);
+            if (!payment)
+                return null;
+            const newRefunded = input.refundedAmount.toFixed(2);
+            const nextStatus = input.fullyRefunded
+                ? 'refunded'
+                : input.refundedAmount > 0 && payment.status !== 'refunded'
+                    ? 'partially_refunded'
+                    : payment.status;
+            const changed = payment.refundedAmount !== newRefunded || payment.status !== nextStatus;
+            payment.refundedAmount = newRefunded;
+            payment.status = nextStatus;
+            payment.providerDetails = {
+                ...(payment.providerDetails ?? {}),
+                ...(input.providerDetails ?? {}),
+                // Stamp the refund time only when the total actually moved, so a
+                // re-delivered webhook does not bump the recorded refund timestamp.
+                ...(changed ? { refundedAt: new Date().toISOString() } : {}),
+                ...(input.externalRefundId ? { refundReference: input.externalRefundId } : {}),
+            };
+            // Only a full refund flips the order's payment status; a partial refund is
+            // tracked on the payment while the order stays 'paid'. The port is
+            // therefore asked only on a full refund — which is also the only branch
+            // that ever needed the order: `Boolean(order) && input.fullyRefunded` was
+            // false for every partial one whether the order existed or not, so the
+            // read this replaces was doing no work on that path.
+            const refunded = input.fullyRefunded
+                ? await this.orderPaymentStatus.applyPaymentStatus(tx, {
+                    orderId: payment.orderId,
+                    paymentStatus: 'refunded',
+                })
+                : null;
+            const holdsTheOrder = refunded !== null;
+            await tx.flush();
+            return { payment, changed, holdsTheOrder };
+        });
+        if (!result)
+            return null;
+        /**
+         * The hold goes through the lifecycle too, after the commit, for the same
+         * reason `receive()` does (feature 085 Phase D). This was the third of the
+         * three sites that assigned `order.status` directly, and it is the one an
+         * operator is most likely to meet: a fully refunded order held for review
+         * whose stock nothing had released.
+         *
+         * Asked on every full refund rather than only on a *changed* one, as the
+         * assignment it replaces was: a re-delivered webhook finds the order
+         * already on hold and the port answers `already_there`, which writes no
+         * second audit entry and emits no second event.
+         */
+        if (result.holdsTheOrder) {
+            await this.moveOrder(result.payment.orderId, ORDER_STATUS_ON_HOLD, 'status_on_failure', null, 'Fully refunded; held for operator review.');
+        }
+        if (result.changed && this.events) {
+            this.events.emit('payment.refunded.v1', {
+                eventId: randomUUID(),
+                occurredAt: new Date().toISOString(),
+                orderId: result.payment.orderId,
+                paymentId: result.payment.id,
+                refundedAmount: Number(result.payment.refundedAmount),
+                currency: input.currency,
+                fullyRefunded: input.fullyRefunded,
+                externalRefundId: input.externalRefundId ?? null,
+            });
+        }
+        return { paymentId: result.payment.id, changed: result.changed };
+    }
+    async resolvePaymentForRefund(tx, input) {
+        if (input.paymentId)
+            return tx.findOne(Payment, { id: input.paymentId });
+        if (input.externalReference) {
+            const byRef = await tx.findOne(Payment, { externalReference: input.externalReference });
+            if (byRef)
+                return byRef;
+        }
+        if (input.orderId) {
+            // The settled payment for the order (most recent attempt).
+            return tx.findOne(Payment, { orderId: input.orderId, status: { $in: ['paid', 'partially_refunded', 'refunded'] } }, { orderBy: { attemptNo: 'desc' } });
+        }
+        return null;
+    }
+    async resolvePayment(tx, input) {
+        if (input.paymentId) {
+            return tx.findOne(Payment, { id: input.paymentId });
+        }
+        if (input.orderId && input.externalReference) {
+            const byRef = await tx.findOne(Payment, {
+                orderId: input.orderId,
+                externalReference: input.externalReference,
+            });
+            if (byRef)
+                return byRef;
+            // Fall back to the most recent open attempt for the order.
+            return tx.findOne(Payment, { orderId: input.orderId }, { orderBy: { attemptNo: 'desc' } });
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=receive-payment-handler.js.map

package/dist/backend/services/receive-payment-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receive-payment-handler.js","sourceRoot":"","sources":["../../../src/backend/services/receive-payment-handler.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/registry-singleton.d.ts

@@ -0,0 +1,16 @@
+import { GatewayRefundRegistry } from './gateway-refund-registry.js';
+/**
+ * Process-wide GatewayRefundRegistry (feature 049).
+ *
+ * The four gateway modules import this instance directly and push their refund
+ * handlers into it from their `ctx.onBoot` hook, so the platform has exactly
+ * one table of handlers however many times it is composed. A module contributes
+ * only the handler it owns, and names itself when it does.
+ *
+ * The presence probe is wired here rather than in the class, for the reason its
+ * twin in `payment_methods` gives: this is the one instance that participates
+ * in the platform's lifecycle, and a registry a test builds for itself should
+ * keep answering about the handlers that test registered.
+ */
+export declare const gatewayRefundRegistry: GatewayRefundRegistry;
+//# sourceMappingURL=registry-singleton.d.ts.map

package/dist/backend/services/registry-singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-singleton.d.ts","sourceRoot":"","sources":["../../../src/backend/services/registry-singleton.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,uBAEjC,CAAC"}

package/dist/backend/services/registry-singleton.js

@@ -0,0 +1,17 @@
+import { effectiveState } from '@endora-commerce/platform/kernel';
+import { GatewayRefundRegistry } from './gateway-refund-registry.js';
+/**
+ * Process-wide GatewayRefundRegistry (feature 049).
+ *
+ * The four gateway modules import this instance directly and push their refund
+ * handlers into it from their `ctx.onBoot` hook, so the platform has exactly
+ * one table of handlers however many times it is composed. A module contributes
+ * only the handler it owns, and names itself when it does.
+ *
+ * The presence probe is wired here rather than in the class, for the reason its
+ * twin in `payment_methods` gives: this is the one instance that participates
+ * in the platform's lifecycle, and a registry a test builds for itself should
+ * keep answering about the handlers that test registered.
+ */
+export const gatewayRefundRegistry = new GatewayRefundRegistry(undefined, (moduleId) => effectiveState.isPresent(moduleId));
+//# sourceMappingURL=registry-singleton.js.map

package/dist/backend/services/registry-singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-singleton.js","sourceRoot":"","sources":["../../../src/backend/services/registry-singleton.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,qBAAqB,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CACrF,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CACnC,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,210 @@
+/**
+ * The error codes this module declares (D-182,
+ * `specs/090-module-owned-error-codes/`).
+ *
+ * Branded, so a typo at a raise site is a compile error rather than a code that
+ * travels the whole path and renders raw to whoever reads it. They live in this
+ * file because it is the one the package publishes at its root subpath: a
+ * sibling module under `src/` is reachable through no subpath at all, so the
+ * raise sites could name it and a consumer branching on the code could not.
+ *
+ * Declaring them in `errorCodes` below is a separate act and is what routes the
+ * sentence to this package's own `i18n/` bundle; the reasoning for the three is
+ * written there.
+ */
+export declare const paymentsErrorCodes: {
+    readonly PAYMENT_NOT_DUE: import("@endora-commerce/contracts").ModuleErrorCode;
+    readonly PAYMENT_ORDER_CLOSED: import("@endora-commerce/contracts").ModuleErrorCode;
+    readonly PAYMENT_ADAPTER_UNAVAILABLE: import("@endora-commerce/contracts").ModuleErrorCode;
+};
+export declare const paymentsSettingsManifest: {
+    moduleCode: string;
+    groups: {
+        code: string;
+        name: string;
+        salesChannelCodes?: string[] | undefined;
+        isSystemProtected?: boolean | undefined;
+    }[];
+    settings: {
+        code: string;
+        name: string;
+        valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+        defaultValue: unknown;
+        description?: string | undefined;
+        groupCode?: string | undefined;
+        previousDefaultValues?: unknown[] | undefined;
+        salesChannelCodes?: string[] | undefined;
+        enumOptions?: string[] | undefined;
+        configurationType?: string | undefined;
+        hidden?: boolean | undefined;
+    }[];
+};
+/**
+ * Payments module — manifest backfill (Module Lifecycle, feature 018).
+ *
+ * Predates the lifecycle system; this manifest is the static record
+ * required so the module participates in the registry. No install /
+ * uninstall hook today — the module's schema is owned by earlier
+ * platform-wide migrations.
+ */
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("email" | "invoice" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "text" | "textarea" | "select" | "radio" | "external" | "uuid" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("email" | "invoice" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB;;;;CAI7B,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;CAmBnC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsInB,CAAC"}