@endora-commerce/contracts 0.100.0

package/dist/payment-return-url.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Where a payment gateway hands the buyer back (issues #274, #287).
+ *
+ * Issue #274 moved all four gateways off `/checkout/*` and onto the order's
+ * own page, on the ground that every `/checkout/*` route is a **placement**
+ * surface and returning a buyer whose order already exists to one is how a
+ * shop gets a second order for the same goods. The first half of that stands;
+ * the destination does not. The owner ruled that **a correct payment lands on
+ * the success page and a failed one on the failure page**, and that the pages
+ * are to be corrected rather than the routing.
+ *
+ * PayU's `continueUrl` and Autopay's `ReturnURL` are one URL for every
+ * outcome, so that ruling cannot be expressed in gateway configuration. So
+ * every gateway hook — the two that discriminate and the two that cannot —
+ * points here, at a landing that places nothing: it reads the order's own
+ * payment state and forwards to success, to failure, or to a wait while the
+ * gateway's confirmation is still in flight. One behaviour, not two.
+ *
+ * Kept here rather than four times over because the rule is the platform's,
+ * not any one gateway's, and `check:module-boundary` (rightly) forbids the
+ * gateway modules from sharing it between themselves.
+ */
+/**
+ * What the gateway said as it handed the buyer back.
+ *
+ * - `returned` — the gateway sent the buyer back and did not say how it went
+ *   (PayU `continueUrl`, Autopay `ReturnURL`), or it says the payment went
+ *   through (Stripe `success_url`, TPay `successUrl`) — which is a claim the
+ *   platform will not take from a URL, since the same URL fires a purchase
+ *   conversion and a buyer can replay it. The settlement notification is the
+ *   authority, and it may not have arrived yet.
+ * - `cancelled` — the buyer left the gateway without paying (Stripe
+ *   `cancel_url` fires on *back*, not on a decline). Nothing was charged and
+ *   the order is waiting to be paid.
+ * - `failed` — the gateway reported the attempt as unsuccessful (TPay
+ *   `errorUrl`).
+ *
+ * The landing trusts this **downwards only**: `failed` and `cancelled` show
+ * the failure page before our own notification lands, which costs nothing
+ * because that page only offers to pay the same order again and re-reads the
+ * order every time. No value here can produce a success page.
+ */
+export type PaymentReturnOutcome = 'returned' | 'cancelled' | 'failed';
+/**
+ * Build the post-payment landing for `orderId`:
+ * `/checkout/return?id=<orderId>&outcome=<outcome>`.
+ *
+ * The outcome is a hint for the landing's decision, never the payment's
+ * status — a gateway's return URL is a browser redirect the buyer can replay,
+ * so the order's own `paymentStatus` stays the authority.
+ */
+export declare function storefrontPaymentReturnUrl(storefrontBaseUrl: string, orderId: string, outcome: PaymentReturnOutcome): string;
+//# sourceMappingURL=payment-return-url.d.ts.map

package/dist/payment-return-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-return-url.d.ts","sourceRoot":"","sources":["../src/payment-return-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEvE;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAGR"}

package/dist/payment-return-url.js

@@ -0,0 +1,35 @@
+/**
+ * Where a payment gateway hands the buyer back (issues #274, #287).
+ *
+ * Issue #274 moved all four gateways off `/checkout/*` and onto the order's
+ * own page, on the ground that every `/checkout/*` route is a **placement**
+ * surface and returning a buyer whose order already exists to one is how a
+ * shop gets a second order for the same goods. The first half of that stands;
+ * the destination does not. The owner ruled that **a correct payment lands on
+ * the success page and a failed one on the failure page**, and that the pages
+ * are to be corrected rather than the routing.
+ *
+ * PayU's `continueUrl` and Autopay's `ReturnURL` are one URL for every
+ * outcome, so that ruling cannot be expressed in gateway configuration. So
+ * every gateway hook — the two that discriminate and the two that cannot —
+ * points here, at a landing that places nothing: it reads the order's own
+ * payment state and forwards to success, to failure, or to a wait while the
+ * gateway's confirmation is still in flight. One behaviour, not two.
+ *
+ * Kept here rather than four times over because the rule is the platform's,
+ * not any one gateway's, and `check:module-boundary` (rightly) forbids the
+ * gateway modules from sharing it between themselves.
+ */
+/**
+ * Build the post-payment landing for `orderId`:
+ * `/checkout/return?id=<orderId>&outcome=<outcome>`.
+ *
+ * The outcome is a hint for the landing's decision, never the payment's
+ * status — a gateway's return URL is a browser redirect the buyer can replay,
+ * so the order's own `paymentStatus` stays the authority.
+ */
+export function storefrontPaymentReturnUrl(storefrontBaseUrl, orderId, outcome) {
+    const base = storefrontBaseUrl.replace(/\/+$/, '');
+    return `${base}/checkout/return?id=${encodeURIComponent(orderId)}&outcome=${outcome}`;
+}
+//# sourceMappingURL=payment-return-url.js.map

package/dist/payment-return-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-return-url.js","sourceRoot":"","sources":["../src/payment-return-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAwBH;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,iBAAyB,EACzB,OAAe,EACf,OAA6B;IAE7B,MAAM,IAAI,GAAG,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnD,OAAO,GAAG,IAAI,uBAAuB,kBAAkB,CAAC,OAAO,CAAC,YAAY,OAAO,EAAE,CAAC;AACxF,CAAC"}

package/dist/payments.d.ts

@@ -0,0 +1,386 @@
+import { z } from 'zod';
+import type { ReceivePayment } from './payment-methods.js';
+import type { PaymentRefundInput, PaymentRefundResult } from './returns.js';
+/**
+ * Payments (FR-072). Drivers: bank_transfer, pickup, credit_limit, gateway.
+ * Driver-specific NextAction payloads live in orders.ts (the Place Order
+ * response body).
+ */
+export declare const paymentMethodKindSchema: z.ZodEnum<{
+    bank_transfer: "bank_transfer";
+    pickup: "pickup";
+    credit_limit: "credit_limit";
+    gateway: "gateway";
+}>;
+export type PaymentMethodKind = z.infer<typeof paymentMethodKindSchema>;
+export declare const paymentMethodSchema: z.ZodObject<{
+    id: z.ZodString;
+    code: z.ZodString;
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        bank_transfer: "bank_transfer";
+        pickup: "pickup";
+        credit_limit: "credit_limit";
+        gateway: "gateway";
+    }>;
+    status: z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+    }>;
+}, z.core.$strip>;
+export type PaymentMethod = z.infer<typeof paymentMethodSchema>;
+export declare const paymentSchema: z.ZodObject<{
+    id: z.ZodString;
+    orderId: z.ZodString;
+    paymentMethodId: z.ZodString;
+    status: z.ZodEnum<{
+        paid: "paid";
+        awaiting_payment: "awaiting_payment";
+        failed: "failed";
+        deferred: "deferred";
+        refunded: "refunded";
+    }>;
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+    paidAt: z.ZodNullable<z.ZodString>;
+    externalReference: z.ZodNullable<z.ZodString>;
+    providerDetails: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    failureReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    attemptNo: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type Payment = z.infer<typeof paymentSchema>;
+/**
+ * What a buyer is told to do next after asking to pay an unpaid order again
+ * (issue #264). The three kinds are the `StartPaymentResult` a payment adapter
+ * returns, carried out to the storefront: send the buyer to the gateway, show
+ * them the transfer details again, or tell them there is nothing to do here.
+ */
+export declare const paymentRetryNextActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"redirect">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"awaiting_transfer">;
+    iban: z.ZodNullable<z.ZodString>;
+    reference: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type PaymentRetryNextAction = z.infer<typeof paymentRetryNextActionSchema>;
+/**
+ * The reply to `POST /api/v1/orders/:orderId/payments/retry` (issue #264).
+ *
+ * `opened` is the difference between the two things the buyer's click can
+ * mean, and the storefront routes on it:
+ *
+ *  - `true`  — the previous attempt had failed, so attempt `attemptNo` was
+ *              opened and its provider session started. `nextAction` is that
+ *              session.
+ *  - `false` — an attempt was already open (a double-click, a reload, a buyer
+ *              coming back to a payment they abandoned). Nothing was opened and
+ *              no provider was contacted, so `nextAction` is `none` and the
+ *              buyer belongs on the existing payment step for that attempt.
+ *
+ * That split is what makes the endpoint idempotent at the provider: one click
+ * is one provider object, whatever the buyer does to the button. It matters
+ * concretely rather than tidily — PayU keys its order on `extOrderId`, which is
+ * this platform's payment id, and a second create against a live attempt would
+ * be a duplicate `extOrderId` at the POS.
+ */
+export declare const paymentRetryResultSchema: z.ZodObject<{
+    paymentId: z.ZodString;
+    attemptNo: z.ZodNumber;
+    opened: z.ZodBoolean;
+    nextAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"none">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"redirect">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"awaiting_transfer">;
+        iban: z.ZodNullable<z.ZodString>;
+        reference: z.ZodString;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+export type PaymentRetryResult = z.infer<typeof paymentRetryResultSchema>;
+export declare const deliveryMethodSchema: z.ZodObject<{
+    id: z.ZodString;
+    code: z.ZodString;
+    name: z.ZodString;
+    cost: z.ZodNumber;
+    currency: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+    }>;
+}, z.core.$strip>;
+export type DeliveryMethod = z.infer<typeof deliveryMethodSchema>;
+export type PaymentAttemptStatus = 'awaiting_payment' | 'paid' | 'failed' | 'deferred' | 'refunded' | 'partially_refunded';
+/**
+ * A payment attempt as it crosses a module boundary — a plain shape, never the
+ * ORM entity (FR-011).
+ *
+ * `amount` and `refundedAmount` stay strings. They are `decimal(14,2)`, and
+ * every consumer of this record is a gateway that forwards the figure to a
+ * payment provider; a `number` cannot round-trip it.
+ */
+export interface PaymentRecord {
+    id: string;
+    orderId: string;
+    paymentMethodId: string;
+    status: PaymentAttemptStatus;
+    amount: string;
+    refundedAmount: string;
+    currency: string;
+    paidAt: Date | null;
+    externalReference: string | null;
+    providerDetails: Record<string, unknown> | null;
+    failureReason: string | null;
+    attemptNo: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Container name: `paymentReadPort`. Owner: `payments`.
+ *
+ * The four gateways resolve a payment attempt by order, by id or by the
+ * provider's own reference — sixteen sites of `em.findOne(Payment, …)` written
+ * out four times over, once per gateway, with slightly different ordering
+ * rules for "the latest attempt".
+ *
+ * When `payments` is off every method fails closed. That is the answer a
+ * gateway webhook should get: a 503 makes the provider retry, where an
+ * invented `null` would make the gateway record a payment nothing accounted
+ * for.
+ */
+export interface PaymentReadPort {
+    findById(id: string): Promise<PaymentRecord | null>;
+    /** Attempts for an order, newest attempt first. */
+    listByOrderId(orderId: string): Promise<PaymentRecord[]>;
+    /** The most recent attempt for an order, or `null` when there is none. */
+    findLatestForOrder(orderId: string): Promise<PaymentRecord | null>;
+    /** Resolve by the provider's own reference (a PaymentIntent id, an order id at the PSP). */
+    findByExternalReference(externalReference: string): Promise<PaymentRecord | null>;
+    /**
+     * How many attempts reference a payment method — the delete-guard
+     * `payment_methods` runs before removing one (feature 034 FR-003, feature
+     * 075).
+     *
+     * A count rather than the rows: the guard needs "is this method still spoken
+     * for", and the figure goes into the operator's 409 message. Handing back
+     * every attempt for a method a busy shop has used for a year would be a read
+     * of unbounded size for a yes/no question.
+     *
+     * It runs on this port's own `EntityManager`, so it does **not** join the
+     * caller's transaction. That costs nothing here and is worth saying: the
+     * deleting transaction writes no `payments` row, and under `read committed`
+     * an in-transaction count took a fresh snapshot per statement anyway — it
+     * never held a concurrent attempt off. What guarantees no orphan is the
+     * guard plus this module refusing to record an attempt against a method that
+     * is gone, not the instant the count was taken.
+     */
+    countByPaymentMethod(paymentMethodId: string): Promise<number>;
+}
+/**
+ * Container name: `paymentReferencePort`. Owner: `payments`.
+ *
+ * The one **write** the four gateways make into this module's table, and the
+ * only one they make anywhere outside the settlement ingress: when a gateway
+ * has created its own object for an attempt — a Stripe PaymentIntent or
+ * Checkout Session, a TPay transaction, a PayU order, an Autopay transaction —
+ * it records that object's identifier on the attempt, so a later provider
+ * event that carries only the provider's own reference resolves back to a
+ * payment. It is the write side of `PaymentReadPort.findByExternalReference`.
+ *
+ * Two methods rather than one, because the four gateways genuinely do two
+ * different things and neither is wrong: `stampExternalReference` replaces
+ * whatever was there (TPay, PayU — a new provider object supersedes the old
+ * one, and keeping the stale reference would strand the settlement event),
+ * while `stampExternalReferenceIfAbsent` keeps a reference already on the row
+ * (Stripe — a redirect Checkout Session and the PaymentIntent it later spawns
+ * are two identifiers for one attempt, and the first is the one its metadata
+ * was written against). Publishing the divergence is how it becomes a decision
+ * somebody can take; hiding it behind one method would have taken it silently.
+ *
+ * Each returns whether the row changed.
+ *
+ * When `payments` is off the write fails closed, and a gateway that has just
+ * created a provider object must hear that: swallowing it would leave a live
+ * PaymentIntent at the provider with nothing on this side able to resolve the
+ * event it will send.
+ *
+ * `mergeProviderDetails` is the same surface seen through the other column
+ * `payments` keeps for a provider: `providerDetails` is what the provider
+ * recorded about an attempt, and `PaymentReadPort.findById` is where a gateway
+ * reads it back. TPay is the one consumer — a BLIK payment that asked for
+ * one-click registration has to carry that request from the pay call to the
+ * settlement notification, which is a different process lifetime — and it is a
+ * merge rather than a set because the settlement path writes the same column.
+ */
+export interface PaymentReferencePort {
+    stampExternalReference(paymentId: string, externalReference: string): Promise<boolean>;
+    /** Stamp only when the attempt carries no reference yet. */
+    stampExternalReferenceIfAbsent(paymentId: string, externalReference: string): Promise<boolean>;
+    /**
+     * Shallow-merge `patch` into the attempt's `providerDetails`. Returns whether
+     * a row was found; a `null` value in `patch` is stored as `null`, not
+     * treated as a deletion.
+     */
+    mergeProviderDetails(paymentId: string, patch: Record<string, unknown>): Promise<boolean>;
+}
+export interface ReceivePaymentResult {
+    paymentId: string;
+    status: PaymentAttemptStatus;
+    orderStatus: string | null;
+    idempotent: boolean;
+}
+/** What a gateway reports when a provider reflects a refund back to us. */
+export interface ReflectRefundInput {
+    paymentId?: string;
+    orderId?: string;
+    /** The provider's own reference — resolves the payment when no `paymentId`. */
+    externalReference?: string;
+    /** Cumulative refunded amount in major units. */
+    refundedAmount: number;
+    currency: string;
+    fullyRefunded: boolean;
+    externalRefundId?: string | null;
+    providerDetails?: Record<string, unknown>;
+}
+/**
+ * Container name: `receivePaymentPort`. Owner: `payments`.
+ *
+ * The ingress every gateway funnels a provider event through (feature 034,
+ * FR-022/FR-023/FR-025). It resolves the payment, applies the outcome and maps
+ * the order status through the method's `statusOnSuccess` / `statusOnFailure`.
+ *
+ * Idempotent by contract: a success after a terminal `paid` is a no-op, a
+ * failure after `paid` is rejected — no downgrade. It resolves a late event
+ * even when the adapter has since been de-registered, because it keys on the
+ * persisted payment rather than on the live registry.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `payments` has an off state at all is its manifest's
+ * `activation` to say, not this line's: a module declaring
+ * `nonDeactivatable` never enters one.
+ */
+export interface ReceivePaymentPort {
+    receive(input: ReceivePayment): Promise<ReceivePaymentResult>;
+    reflectRefund(input: ReflectRefundInput): Promise<{
+        paymentId: string;
+        changed: boolean;
+    } | null>;
+}
+/**
+ * A gateway's refund handler, as the host registry holds it.
+ *
+ * The four gateway modules contribute one each from their boot hook. The
+ * registry's absent-owner policy is `payments`' and stays `payments`': a
+ * handler whose module is switched off is **skipped**, and the obligation
+ * lands on `pending_manual` rather than being dropped. Refunding through a PSP
+ * the operator switched off would charge that PSP's API with that operator's
+ * credentials — the opposite of "behaves as if never installed"
+ * (Principle XVII).
+ */
+export interface GatewayRefundHandler {
+    /** The payment adapter key this handler serves (e.g. `stripe`). */
+    readonly adapterKey: string;
+    refund(input: PaymentRefundInput): Promise<PaymentRefundResult>;
+}
+/**
+ * Container name: `gatewayRefundRegistry`. Owner: `payments`.
+ *
+ * A **contribution seam**, not a call seam: the gateways push into it at boot
+ * and the host filters at enumeration, keyed on the module recorded with each
+ * entry. The deactivation-consequence classification of every edge into it is
+ * `contributes`, and publishing the shape must not change that — a cut that
+ * turned these into `fails-closed` would change the sentence the operator's
+ * confirmation dialog renders (contracts/port-publication.md §1.4).
+ *
+ * **The name above is the ungated one, and that is the whole instruction to an
+ * implementer** (D-99.7). `gatewayRefundRegistry` is a plain `di.register`: a
+ * gateway resolves it and calls `register` from its `ctx.onBoot` hook, exactly
+ * as `stripe`, `payu`, `tpay` and `autopay` do. It is ungated **because a gate
+ * on a push refuses the contribution rather than deferring it** — a gateway
+ * that booted while `payments` was off would stay silently unregistered until
+ * the next restart after an operator switched `payments` back on.
+ *
+ * A gated twin, `gatewayRefundRegistryPort`, used to be published over this
+ * same interface and was resolved by nobody. It is gone: an author following it
+ * would resolve a gated registration from a boot hook, and a `ModuleDisabledError`
+ * raised during composition is re-thrown as `ModuleCompositionError` and ends
+ * in `process.exit(1)`. The pull direction is real but intra-module —
+ * `payments`' own refund provider asks this registry which handler settles a
+ * refund — and it is not published.
+ *
+ * `register` therefore names its contributor. That argument is the whole
+ * mechanism: without it the registry records no owner, states no policy, and a
+ * switched-off gateway goes on refunding through its own PSP API — which is
+ * what D-44 §7 recorded as the one live instance of that gap.
+ *
+ * **What an implementer inherits while their own module is off:** the handler
+ * is *skipped* at enumeration, not dropped. The refund does not silently fail —
+ * `payments` records a `pending_manual` obligation naming the absent module, so
+ * a person settles it, which is what a deployment that never installed the
+ * gateway already gets (D-71).
+ *
+ * **Do not "complete" this interface.** `GatewayRefundRegistry` also has
+ * `entry`, `ownerOf`, `listAll` and `absentOwnerFor`, and the omission is the
+ * point rather than an oversight: `absentOwnerFor` is what turns a refund
+ * through an absent gateway into a `pending_manual` obligation instead of a
+ * refund that did not happen (D-71), and it is called from exactly one place —
+ * `payments/services/payment-refund.ts` — plus this module's own unit test.
+ * Verified for issue #192: no caller outside `payments`. Publishing it would
+ * offer another module a presence-blind read of the table, which is the one
+ * thing the contribution classification rests on not existing.
+ */
+export interface GatewayRefundRegistryPort {
+    register(handler: GatewayRefundHandler, module: string): void;
+    /** The handler for an adapter key, or `undefined` when its owner is absent. */
+    get(adapterKey: string): GatewayRefundHandler | undefined;
+    /**
+     * The handler for an adapter key, falling back to the sole registered one
+     * when the order names no adapter. Absent owners are skipped here too:
+     * honouring one would route exactly the refunds with the least information
+     * behind them into a switched-off gateway.
+     */
+    resolve(adapterKey?: string | null): GatewayRefundHandler | undefined;
+    /** Adapter keys whose owner is present, in registration order. */
+    list(): string[];
+}
+/** What the order-confirmation e-mail knows about the payment method. */
+export interface PaymentEmailContext {
+    /** Resolved display name of the payment method. */
+    name: string;
+    kind: string;
+    /** Flat surcharge applied for this method (order currency). */
+    additionalPrice: number;
+    currency: string;
+}
+/**
+ * Container name: `paymentEmailRendererPort`. Owner: `payments`.
+ *
+ * The payment line of the transactional order-confirmation e-mail (feature
+ * 034, FR-016/FR-017). An adapter may register a custom renderer under a key;
+ * when none is registered the platform default is used, so the payment section
+ * always renders.
+ *
+ * `orders` reaches the resolver today and then calls the function it gets
+ * back. The port collapses those two steps, which is what lets the fallback
+ * stay on this side: a consumer that resolved a renderer and got `undefined`
+ * would have to hold a copy of the default text, and two copies of a default
+ * are how a default stops being one.
+ *
+ * Bodies are plain text (see `EmailMailerSendInput.text`), so a renderer is a
+ * `(ctx) => string` builder rather than a component.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `payments` has an off state at all is its manifest's
+ * `activation` to say, not this line's: a module declaring
+ * `nonDeactivatable` never enters one.
+ */
+export interface PaymentEmailRendererPort {
+    render(rendererKey: string | null, ctx: PaymentEmailContext): string;
+}
+//# sourceMappingURL=payments.d.ts.map

package/dist/payments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payments.d.ts","sourceRoot":"","sources":["../src/payments.ts"],"names":[],"mappings":"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"}

package/dist/payments.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { isoDateTimeSchema, paymentStatusSchema, uuidSchema } from './common.js';
+/**
+ * Payments (FR-072). Drivers: bank_transfer, pickup, credit_limit, gateway.
+ * Driver-specific NextAction payloads live in orders.ts (the Place Order
+ * response body).
+ */
+export const paymentMethodKindSchema = z.enum([
+    'bank_transfer',
+    'pickup',
+    'credit_limit',
+    'gateway',
+]);
+export const paymentMethodSchema = z.object({
+    id: uuidSchema,
+    code: z.string(),
+    name: z.string(),
+    kind: paymentMethodKindSchema,
+    status: z.enum(['active', 'inactive']),
+});
+export const paymentSchema = z.object({
+    id: uuidSchema,
+    orderId: uuidSchema,
+    paymentMethodId: uuidSchema,
+    status: paymentStatusSchema,
+    amount: z.number().finite().nonnegative(),
+    currency: z.string().length(3),
+    paidAt: isoDateTimeSchema.nullable(),
+    externalReference: z.string().nullable(),
+    // Feature 034 — payment-process detail captured by the adapter on receive_payment.
+    providerDetails: z.record(z.string(), z.unknown()).nullable().optional(),
+    failureReason: z.string().nullable().optional(),
+    attemptNo: z.number().int().positive().default(1),
+});
+/**
+ * What a buyer is told to do next after asking to pay an unpaid order again
+ * (issue #264). The three kinds are the `StartPaymentResult` a payment adapter
+ * returns, carried out to the storefront: send the buyer to the gateway, show
+ * them the transfer details again, or tell them there is nothing to do here.
+ */
+export const paymentRetryNextActionSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('none') }),
+    z.object({ kind: z.literal('redirect'), url: z.string().url() }),
+    z.object({
+        kind: z.literal('awaiting_transfer'),
+        iban: z.string().nullable(),
+        reference: z.string(),
+    }),
+]);
+/**
+ * The reply to `POST /api/v1/orders/:orderId/payments/retry` (issue #264).
+ *
+ * `opened` is the difference between the two things the buyer's click can
+ * mean, and the storefront routes on it:
+ *
+ *  - `true`  — the previous attempt had failed, so attempt `attemptNo` was
+ *              opened and its provider session started. `nextAction` is that
+ *              session.
+ *  - `false` — an attempt was already open (a double-click, a reload, a buyer
+ *              coming back to a payment they abandoned). Nothing was opened and
+ *              no provider was contacted, so `nextAction` is `none` and the
+ *              buyer belongs on the existing payment step for that attempt.
+ *
+ * That split is what makes the endpoint idempotent at the provider: one click
+ * is one provider object, whatever the buyer does to the button. It matters
+ * concretely rather than tidily — PayU keys its order on `extOrderId`, which is
+ * this platform's payment id, and a second create against a live attempt would
+ * be a duplicate `extOrderId` at the POS.
+ */
+export const paymentRetryResultSchema = z.object({
+    paymentId: uuidSchema,
+    attemptNo: z.number().int().positive(),
+    opened: z.boolean(),
+    nextAction: paymentRetryNextActionSchema,
+});
+export const deliveryMethodSchema = z.object({
+    id: uuidSchema,
+    code: z.string(),
+    name: z.string(),
+    cost: z.number().finite().nonnegative(),
+    currency: z.string().length(3),
+    status: z.enum(['active', 'inactive']),
+});
+//# sourceMappingURL=payments.js.map

package/dist/payments.js.map

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

package/dist/pim-connector.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+export declare const pimImportRunStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    skipped: "skipped";
+    queued: "queued";
+    running: "running";
+    completed_with_issues: "completed_with_issues";
+}>;
+export type PimImportRunStatus = z.infer<typeof pimImportRunStatusSchema>;
+export declare const pimImportTriggerSchema: z.ZodEnum<{
+    push: "push";
+    scheduled: "scheduled";
+    manual: "manual";
+}>;
+export type PimImportTrigger = z.infer<typeof pimImportTriggerSchema>;
+export declare const pimImportModeSchema: z.ZodEnum<{
+    delta: "delta";
+    full: "full";
+}>;
+export type PimImportMode = z.infer<typeof pimImportModeSchema>;
+export declare const pimImportIssueSeveritySchema: z.ZodEnum<{
+    error: "error";
+    info: "info";
+    warning: "warning";
+}>;
+export type PimImportIssueSeverity = z.infer<typeof pimImportIssueSeveritySchema>;
+export declare const pimImportCountsSchema: z.ZodObject<{
+    considered: z.ZodNumber;
+    created: z.ZodNumber;
+    updated: z.ZodNumber;
+    skipped: z.ZodNumber;
+    withdrawn: z.ZodNumber;
+    failed: z.ZodNumber;
+    protected: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PimImportCounts = z.infer<typeof pimImportCountsSchema>;
+/** Canonical field-protection path grammar (shared across PIM connectors). */
+export declare const pimFieldPathSchema: z.ZodString;
+export type PimFieldPath = z.infer<typeof pimFieldPathSchema>;
+export declare const PIM_CONNECTOR_REGISTRY_PORT: "pimConnectorRegistryPort";
+/**
+ * Container name: `pimConnectorRegistryPort`. Owner: `pim_connector`.
+ *
+ * Mutual-exclusion registry — see
+ * `specs/089-unopim-pim-sync/contracts/pim-connector-shared.md`. The name is
+ * the whole of the promise this port makes (D-98.2): `lazyPort<T>` asserts `T`
+ * and compares it to nothing that is registered, so a consumer copying the
+ * owner's class registration instead of this name would compile and receive the
+ * service ungated. `PIM_CONNECTOR_REGISTRY_PORT` above is the same literal, for
+ * the owner's `providePort` call.
+ */
+export interface PimConnectorRegistryPort {
+    /** Refuses when another PIM connector's activation Setting is true. */
+    assertCanActivate(moduleId: string): Promise<void>;
+    recordActive(moduleId: string, adminId: string | null): Promise<void>;
+    clearActive(moduleId: string): Promise<void>;
+    getActiveModuleId(): Promise<string | null>;
+}
+//# sourceMappingURL=pim-connector.d.ts.map

package/dist/pim-connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pim-connector.d.ts","sourceRoot":"","sources":["../src/pim-connector.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,wBAAwB;;;;;;;EAOnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,sBAAsB;;;;EAA0C,CAAC;AAC9E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,mBAAmB;;;EAA4B,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,4BAA4B;;;;EAAuC,CAAC;AACjF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,qBAAqB;;;;;;;;iBAQhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,aAM5B,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,2BAA2B,EAAG,0BAAmC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7C"}