cabloy 5.1.202 → 5.1.203

package/vona/src/suite/a-commerce/modules/commerce-trade/src/.metadata/index.ts

@@ -1063,11 +1063,13 @@ declare module 'vona-module-commerce-trade' {
 /** controller: begin */
 export * from '../controller/cart.ts';
 export * from '../controller/checkout.ts';
+export * from '../controller/e2eFixture.ts';
 export * from '../controller/order.ts';
 export * from '../controller/stockAudit.ts';
 export * from '../controller/stockBalance.ts';
 import type { IControllerOptionsCart } from '../controller/cart.ts';
 import type { IControllerOptionsCheckout } from '../controller/checkout.ts';
+import type { IControllerOptionsE2eFixture } from '../controller/e2eFixture.ts';
 import type { IControllerOptionsOrder } from '../controller/order.ts';
 import type { IControllerOptionsStockAudit } from '../controller/stockAudit.ts';
 import type { IControllerOptionsStockBalance } from '../controller/stockBalance.ts';
@@ -1077,6 +1079,7 @@ declare module 'vona-module-a-web' {
     export interface IControllerRecord {
       'commerce-trade:cart': IControllerOptionsCart;
 'commerce-trade:checkout': IControllerOptionsCheckout;
+'commerce-trade:e2eFixture': IControllerOptionsE2eFixture;
 'commerce-trade:order': IControllerOptionsOrder;
 'commerce-trade:stockAudit': IControllerOptionsStockAudit;
 'commerce-trade:stockBalance': IControllerOptionsStockBalance;
@@ -1108,6 +1111,17 @@ declare module 'vona-module-commerce-trade' {
             get $onionOptions(): IControllerOptionsCheckout;
           }
 
+        export interface ControllerE2eFixture {
+          /** @internal */
+          get scope(): ScopeModuleCommerceTrade;
+        }
+
+          export interface ControllerE2eFixture {
+            get $beanFullName(): 'commerce-trade.controller.e2eFixture';
+            get $onionName(): 'commerce-trade:e2eFixture';
+            get $onionOptions(): IControllerOptionsE2eFixture;
+          }
+
         export interface ControllerOrder {
           /** @internal */
           get scope(): ScopeModuleCommerceTrade;
@@ -1148,6 +1162,8 @@ import type { ControllerCart } from '../controller/cart.ts';
 // @ts-ignore ignore
 import type { ControllerCheckout } from '../controller/checkout.ts';
 // @ts-ignore ignore
+import type { ControllerE2eFixture } from '../controller/e2eFixture.ts';
+// @ts-ignore ignore
 import type { ControllerOrder } from '../controller/order.ts';
 // @ts-ignore ignore
 import type { ControllerStockAudit } from '../controller/stockAudit.ts';
@@ -1163,6 +1179,10 @@ declare module 'vona-module-commerce-trade' {
       actions?: TypeControllerOptionsActions<ControllerCheckout>;
     }
 
+    export interface IControllerOptionsE2eFixture {
+      actions?: TypeControllerOptionsActions<ControllerE2eFixture>;
+    }
+
     export interface IControllerOptionsOrder {
       actions?: TypeControllerOptionsActions<ControllerOrder>;
     }
@@ -1192,6 +1212,9 @@ declare module 'vona-module-a-web' {
 export interface IApiPathPostRecord{
         '/commerce/trade/cart/items': undefined;
 '/commerce/trade/checkout': undefined;
+'/commerce/trade/e2eFixture/catalogue': undefined;
+'/commerce/trade/e2eFixture/order/:orderId/payment/:attemptId/dispatch': undefined;
+'/commerce/trade/e2eFixture/order/:orderId/refund/:attemptId/dispatch': undefined;
 '/commerce/trade/order/:id/requestRefund': undefined;
 '/commerce/trade/order/:id/approveRefund': undefined;
 '/commerce/trade/order/:id/rejectRefund': undefined;
@@ -1207,6 +1230,9 @@ export interface IApiPathPatchRecord{
 export interface IApiPathDeleteRecord{
         '/commerce/trade/cart/items/:id': undefined;
 '/commerce/trade/cart/items': undefined;
+'/commerce/trade/e2eFixture/order/:orderId': undefined;
+'/commerce/trade/e2eFixture/customer': undefined;
+'/commerce/trade/e2eFixture/catalogue/:categoryId': undefined;
     }
 
 }
@@ -1247,6 +1273,7 @@ declare module 'vona' {
 /** bean: end */
 /** service: begin */
 export * from '../service/cart.ts';
+export * from '../service/e2eFixture.ts';
 export * from '../service/order.ts';
 export * from '../service/stockAudit.ts';
 export * from '../service/stockBalance.ts';
@@ -1256,6 +1283,7 @@ declare module 'vona-module-a-bean' {
 
     export interface IServiceRecord {
       'commerce-trade:cart': never;
+'commerce-trade:e2eFixture': never;
 'commerce-trade:order': never;
 'commerce-trade:stockAudit': never;
 'commerce-trade:stockBalance': never;
@@ -1275,6 +1303,16 @@ declare module 'vona-module-commerce-trade' {
             get $onionName(): 'commerce-trade:cart';
           }
 
+        export interface ServiceE2eFixture {
+          /** @internal */
+          get scope(): ScopeModuleCommerceTrade;
+        }
+
+          export interface ServiceE2eFixture {
+            get $beanFullName(): 'commerce-trade.service.e2eFixture';
+            get $onionName(): 'commerce-trade:e2eFixture';
+          }
+
         export interface ServiceOrder {
           /** @internal */
           get scope(): ScopeModuleCommerceTrade;
@@ -1308,11 +1346,13 @@ declare module 'vona-module-commerce-trade' {
 /** service: end */
 /** service: begin */
 import type { ServiceCart } from '../service/cart.ts';
+import type { ServiceE2eFixture } from '../service/e2eFixture.ts';
 import type { ServiceOrder } from '../service/order.ts';
 import type { ServiceStockAudit } from '../service/stockAudit.ts';
 import type { ServiceStockBalance } from '../service/stockBalance.ts';
 export interface IModuleService {
   'cart': ServiceCart;
+'e2eFixture': ServiceE2eFixture;
 'order': ServiceOrder;
 'stockAudit': ServiceStockAudit;
 'stockBalance': ServiceStockBalance;
@@ -1324,6 +1364,7 @@ import 'vona';
 declare module 'vona' {
   export interface IBeanRecordGeneral {
     'commerce-trade.service.cart': ServiceCart;
+'commerce-trade.service.e2eFixture': ServiceE2eFixture;
 'commerce-trade.service.order': ServiceOrder;
 'commerce-trade.service.stockAudit': ServiceStockAudit;
 'commerce-trade.service.stockBalance': ServiceStockBalance;

package/vona/src/suite/a-commerce/modules/commerce-trade/src/controller/e2eFixture.ts

@@ -0,0 +1,52 @@
+import type { TableIdentity } from 'table-identity';
+import type { IDecoratorControllerOptions } from 'vona-module-a-web';
+
+import { BeanBase } from 'vona';
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Arg, Controller, Web } from 'vona-module-a-web';
+
+export interface IControllerOptionsE2eFixture extends IDecoratorControllerOptions {}
+
+// Not part of the application contract: this exists solely for owned, local E2E data.
+@Controller<IControllerOptionsE2eFixture>({
+  path: 'e2eFixture',
+  meta: { mode: ['dev', 'test'] },
+})
+@Api.exclude()
+export class ControllerE2eFixture extends BeanBase {
+  @Web.post('catalogue')
+  async createCatalogue() {
+    return await this.scope.service.e2eFixture.createCatalogue();
+  }
+
+  @Web.post('order/:orderId/payment/:attemptId/dispatch')
+  async dispatchPayment(
+    @Arg.param('orderId', v.tableIdentity()) orderId: TableIdentity,
+    @Arg.param('attemptId', v.tableIdentity()) attemptId: TableIdentity,
+  ) {
+    return await this.scope.service.e2eFixture.dispatchPayment(orderId, attemptId);
+  }
+
+  @Web.post('order/:orderId/refund/:attemptId/dispatch')
+  async dispatchRefund(
+    @Arg.param('orderId', v.tableIdentity()) orderId: TableIdentity,
+    @Arg.param('attemptId', v.tableIdentity()) attemptId: TableIdentity,
+  ) {
+    return await this.scope.service.e2eFixture.dispatchRefund(orderId, attemptId);
+  }
+
+  @Web.delete('order/:orderId')
+  async removeOrder(@Arg.param('orderId', v.tableIdentity()) orderId: TableIdentity) {
+    await this.scope.service.e2eFixture.removeOrder(orderId);
+  }
+
+  @Web.delete('customer')
+  async removeCustomer() {
+    await this.scope.service.e2eFixture.removeCustomer();
+  }
+
+  @Web.delete('catalogue/:categoryId')
+  async removeCatalogue(@Arg.param('categoryId', v.tableIdentity()) categoryId: TableIdentity) {
+    await this.scope.service.e2eFixture.removeCatalogue(categoryId);
+  }
+}

package/vona/src/suite/a-commerce/modules/commerce-trade/src/lib/e2eFixture.ts

@@ -0,0 +1,224 @@
+import type { IPaymentOutcomeEvent, IRefundOutcomeEvent } from 'vona-module-a-pay';
+import type { EntityOutboxEvent, EntityWebhookInbox } from 'vona-module-a-pay';
+
+import { randomUUID } from 'node:crypto';
+
+import type { TypeOrderState } from '../entity/order.tsx';
+import type { EntityOrderAudit, TypeOrderAuditOperation } from '../entity/orderAudit.tsx';
+import type { EntityStockBalance } from '../entity/stockBalance.tsx';
+import type { EntityStockReservation } from '../entity/stockReservation.tsx';
+
+export const fixturePrefix = 'e2e-fixture-';
+
+export function createOwnedFixtureName(userId: string | number) {
+  return `${fixturePrefix}${userId}-${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+}
+const mockProvider = 'pay-mock:mock';
+
+export function isOwnedFixtureName(name: string, userId: string | number) {
+  return new RegExp(`^${fixturePrefix}${userId}-[0-9a-f]{12}$`).test(name);
+}
+
+export function isFixtureCustomer<T extends { name: string; anonymous?: boolean }>(
+  user: T | undefined,
+): user is T {
+  return !!user && !user.anonymous && user.name.startsWith(fixturePrefix);
+}
+
+export function fixtureReservationMatchesLine(
+  reservation: Pick<
+    EntityStockReservation,
+    'skuId' | 'orderLineId' | 'stockBalanceId' | 'quantity'
+  >,
+  line: { id: string | number; skuId: string | number; quantity: number },
+  balance: Pick<EntityStockBalance, 'id' | 'skuId'>,
+) {
+  return (
+    String(reservation.orderLineId) === String(line.id) &&
+    String(reservation.skuId) === String(line.skuId) &&
+    String(reservation.stockBalanceId) === String(balance.id) &&
+    String(balance.skuId) === String(line.skuId) &&
+    reservation.quantity === line.quantity
+  );
+}
+
+export function fixtureAdvancedPaymentAuditMatches(
+  audits: Pick<
+    EntityOrderAudit,
+    'id' | 'orderId' | 'operation' | 'fromState' | 'toState' | 'correlationId'
+  >[],
+  orderId: string | number,
+  state: Extract<TypeOrderState, 'shipped' | 'refunded'>,
+  paymentCorrelationId: string,
+  shipmentCorrelationId?: string,
+  refundCorrelationId?: string,
+) {
+  const expected: Array<{
+    operation: TypeOrderAuditOperation;
+    fromState: TypeOrderState;
+    toState: TypeOrderState;
+  }> = [
+    { operation: 'paid', fromState: 'awaiting_payment', toState: 'paid' },
+    ...(state === 'shipped'
+      ? [{ operation: 'shipped' as const, fromState: 'paid' as const, toState: 'shipped' as const }]
+      : [
+          {
+            operation: 'refund_requested' as const,
+            fromState: 'paid' as const,
+            toState: 'refund_requested' as const,
+          },
+          {
+            operation: 'refund_approved' as const,
+            fromState: 'refund_requested' as const,
+            toState: 'refund_approved' as const,
+          },
+          {
+            operation: 'refunded' as const,
+            fromState: 'refund_approved' as const,
+            toState: 'refunded' as const,
+          },
+        ]),
+  ];
+  const steps = audits.filter(audit => audit.operation !== 'created');
+  return (
+    steps.length === expected.length &&
+    steps.every(
+      (audit, index) =>
+        String(audit.orderId) === String(orderId) &&
+        audit.operation === expected[index].operation &&
+        audit.fromState === expected[index].fromState &&
+        audit.toState === expected[index].toState &&
+        (index !== 0 || audit.correlationId === paymentCorrelationId) &&
+        (state !== 'shipped' || index !== 1 || audit.correlationId === shipmentCorrelationId) &&
+        (state !== 'refunded' || index !== 3 || audit.correlationId === refundCorrelationId),
+    )
+  );
+}
+
+export function fixtureEventNeedsDispatch(event: EntityOutboxEvent, now = new Date()) {
+  if (event.state === 'dispatched') {
+    if (
+      !event.dispatchedAt ||
+      event.claimToken ||
+      event.claimedAt ||
+      event.claimExpiresAt ||
+      event.errorSummary ||
+      event.attemptCount < 1
+    ) {
+      throw new Error('fixture event has inconsistent dispatched state');
+    }
+    return false;
+  }
+  if (
+    event.state !== 'pending' ||
+    event.attemptCount !== 0 ||
+    event.claimToken ||
+    event.claimedAt ||
+    event.claimExpiresAt ||
+    event.dispatchedAt ||
+    event.errorSummary ||
+    (event.nextAttemptAt && event.nextAttemptAt > now)
+  ) {
+    throw new Error('fixture event is not eligible for dispatch');
+  }
+  return true;
+}
+
+export function selectFixtureEvent(
+  events: EntityOutboxEvent[],
+  inboxes: EntityWebhookInbox[],
+  expected: {
+    kind: 'payment' | 'refund';
+    paymentSessionId: string | number;
+    businessReference: string;
+    amountMinor: number;
+    currency: string;
+    refundOperationId?: string | number;
+    clientName: string;
+    environment: 'sandbox' | 'live';
+  },
+) {
+  const eventType = `${expected.kind}.outcome.v1`;
+  const candidates = events.filter(
+    event =>
+      event.eventType === eventType &&
+      String(event.paymentSessionId) === String(expected.paymentSessionId) &&
+      (expected.kind === 'payment'
+        ? !event.refundOperationId
+        : String(event.refundOperationId) === String(expected.refundOperationId)),
+  );
+  if (candidates.length !== 1) throw new Error('fixture outbox event is missing or ambiguous');
+  const event = candidates[0];
+  const payload = event.payload as IPaymentOutcomeEvent | IRefundOutcomeEvent;
+  if (
+    typeof payload?.eventId !== 'string' ||
+    !payload.eventId.startsWith(`mock-${expected.kind}-`) ||
+    String(event.paymentSessionId) !== String(payload.paymentSessionId) ||
+    (expected.kind === 'payment'
+      ? !!event.refundOperationId
+      : String(event.refundOperationId) !==
+        String((payload as IRefundOutcomeEvent).refundOperationId)) ||
+    payload.providerName !== mockProvider ||
+    payload.businessReference !== expected.businessReference ||
+    String(payload.paymentSessionId) !== String(expected.paymentSessionId) ||
+    payload.amountMinor !== expected.amountMinor ||
+    payload.currency !== expected.currency ||
+    !['succeeded', 'failed', 'cancelled'].includes(payload.state) ||
+    (expected.kind === 'refund' &&
+      String((payload as IRefundOutcomeEvent).refundOperationId) !==
+        String(expected.refundOperationId))
+  ) {
+    throw new Error('fixture outbox payload conflicts with the mock operation');
+  }
+  const matchingInboxes = inboxes.filter(
+    inbox =>
+      inbox.providerEventId === payload.eventId &&
+      inbox.providerName === mockProvider &&
+      inbox.clientName === expected.clientName &&
+      inbox.environment === expected.environment,
+  );
+  if (matchingInboxes.length !== 1)
+    throw new Error('fixture webhook inbox is missing or ambiguous');
+  const inbox = matchingInboxes[0];
+  if (
+    inbox.state !== 'processed' ||
+    !inbox.processedAt ||
+    inbox.errorSummary ||
+    inbox.eventType !== `${expected.kind}.${payload.state}` ||
+    String(inbox.paymentSessionId) !== String(expected.paymentSessionId) ||
+    (expected.kind === 'payment'
+      ? !!inbox.refundOperationId || inbox.paymentState !== payload.state
+      : String(inbox.refundOperationId) !== String(expected.refundOperationId) ||
+        inbox.refundState !== payload.state) ||
+    inbox.amountMinor !== expected.amountMinor ||
+    inbox.currency !== expected.currency ||
+    (expected.kind === 'payment' &&
+      (inbox.providerCaptureId ?? undefined) !==
+        ((payload as IPaymentOutcomeEvent).providerCaptureId ?? undefined)) ||
+    (expected.kind === 'refund' &&
+      inbox.providerRefundId !== (payload as IRefundOutcomeEvent).providerRefundId)
+  ) {
+    throw new Error('fixture webhook inbox is not a processed matching terminal outcome');
+  }
+  return { event, payload };
+}
+
+export function selectPaymentFixtureEvent(
+  events: EntityOutboxEvent[],
+  inboxes: EntityWebhookInbox[],
+  expected: Omit<Parameters<typeof selectFixtureEvent>[2], 'kind' | 'refundOperationId'>,
+) {
+  const result = selectFixtureEvent(events, inboxes, { ...expected, kind: 'payment' });
+  return { ...result, payload: result.payload as IPaymentOutcomeEvent };
+}
+
+export function selectRefundFixtureEvent(
+  events: EntityOutboxEvent[],
+  inboxes: EntityWebhookInbox[],
+  expected: Omit<Parameters<typeof selectFixtureEvent>[2], 'kind' | 'refundOperationId'> & {
+    refundOperationId: string | number;
+  },
+) {
+  const result = selectFixtureEvent(events, inboxes, { ...expected, kind: 'refund' });
+  return { ...result, payload: result.payload as IRefundOutcomeEvent };
+}