cabloy 5.1.117 → 5.1.119

package/vona/src/suite/a-commerce/modules/commerce-payment/src/bean/meta.version.ts

@@ -68,5 +68,96 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
         .dateTime(entityPaymentAudit.processedAt)
         .comment(entityPaymentAudit.$comment.processedAt);
     });
+
+    const entityRefundRequest = this.scope.entity.refundRequest;
+    await this.bean.model.createTable(entityRefundRequest.$table, table => {
+      table.comment(entityRefundRequest.$comment.$table);
+      table.basicFields();
+      table
+        .tableIdentity(entityRefundRequest.orderId)
+        .comment(entityRefundRequest.$comment.orderId);
+      table.userId(entityRefundRequest.userId).comment(entityRefundRequest.$comment.userId);
+      table.string(entityRefundRequest.state, 20).comment(entityRefundRequest.$comment.state);
+      table.string(entityRefundRequest.currency, 3).comment(entityRefundRequest.$comment.currency);
+      table
+        .integer(entityRefundRequest.amountCents)
+        .comment(entityRefundRequest.$comment.amountCents);
+      table
+        .string(entityRefundRequest.correlationId, 100)
+        .comment(entityRefundRequest.$comment.correlationId);
+      table.string(entityRefundRequest.reason, 255).comment(entityRefundRequest.$comment.reason);
+      table
+        .userId(entityRefundRequest.reviewedBy)
+        .nullable()
+        .comment(entityRefundRequest.$comment.reviewedBy);
+      table
+        .dateTime(entityRefundRequest.reviewedAt)
+        .nullable()
+        .comment(entityRefundRequest.$comment.reviewedAt);
+      table
+        .dateTime(entityRefundRequest.finalizedAt)
+        .nullable()
+        .comment(entityRefundRequest.$comment.finalizedAt);
+    });
+
+    const entityRefundAttempt = this.scope.entity.refundAttempt;
+    await this.bean.model.createTable(entityRefundAttempt.$table, table => {
+      table.comment(entityRefundAttempt.$comment.$table);
+      table.basicFields();
+      table
+        .tableIdentity(entityRefundAttempt.refundRequestId)
+        .comment(entityRefundAttempt.$comment.refundRequestId);
+      table
+        .tableIdentity(entityRefundAttempt.orderId)
+        .comment(entityRefundAttempt.$comment.orderId);
+      table.userId(entityRefundAttempt.userId).comment(entityRefundAttempt.$comment.userId);
+      table.string(entityRefundAttempt.state, 20).comment(entityRefundAttempt.$comment.state);
+      table.string(entityRefundAttempt.currency, 3).comment(entityRefundAttempt.$comment.currency);
+      table
+        .integer(entityRefundAttempt.amountCents)
+        .comment(entityRefundAttempt.$comment.amountCents);
+      table
+        .string(entityRefundAttempt.correlationId, 100)
+        .comment(entityRefundAttempt.$comment.correlationId);
+      table
+        .dateTime(entityRefundAttempt.finalizedAt)
+        .nullable()
+        .comment(entityRefundAttempt.$comment.finalizedAt);
+    });
+
+    const entityRefundAudit = this.scope.entity.refundAudit;
+    await this.bean.model.createTable(entityRefundAudit.$table, table => {
+      table.comment(entityRefundAudit.$comment.$table);
+      table.basicFields();
+      table
+        .tableIdentity(entityRefundAudit.refundRequestId)
+        .comment(entityRefundAudit.$comment.refundRequestId);
+      table
+        .tableIdentity(entityRefundAudit.refundAttemptId)
+        .nullable()
+        .comment(entityRefundAudit.$comment.refundAttemptId);
+      table.tableIdentity(entityRefundAudit.orderId).comment(entityRefundAudit.$comment.orderId);
+      table.userId(entityRefundAudit.userId).comment(entityRefundAudit.$comment.userId);
+      table
+        .string(entityRefundAudit.toRefundState, 20)
+        .comment(entityRefundAudit.$comment.toRefundState);
+      table
+        .string(entityRefundAudit.attemptState, 20)
+        .nullable()
+        .comment(entityRefundAudit.$comment.attemptState);
+      table
+        .string(entityRefundAudit.idempotencyKey, 100)
+        .nullable()
+        .comment(entityRefundAudit.$comment.idempotencyKey);
+      table
+        .string(entityRefundAudit.correlationId, 100)
+        .comment(entityRefundAudit.$comment.correlationId);
+      table.string(entityRefundAudit.reason, 255).comment(entityRefundAudit.$comment.reason);
+      table
+        .userId(entityRefundAudit.actorId)
+        .nullable()
+        .comment(entityRefundAudit.$comment.actorId);
+      table.dateTime(entityRefundAudit.processedAt).comment(entityRefundAudit.$comment.processedAt);
+    });
   }
 }

package/vona/src/suite/a-commerce/modules/commerce-payment/src/entity/refundAttempt.tsx

@@ -0,0 +1,37 @@
+import type { TableIdentity } from 'table-identity';
+import type { IDecoratorEntityOptions } from 'vona-module-a-orm';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Entity, EntityBase } from 'vona-module-a-orm';
+import { z } from 'zod';
+
+export type TypeRefundAttemptState = 'created' | 'succeeded' | 'failed';
+
+export interface IEntityOptionsRefundAttempt extends IDecoratorEntityOptions {}
+
+@Entity<IEntityOptionsRefundAttempt>('commercePaymentRefundAttempt')
+export class EntityRefundAttempt extends EntityBase {
+  @Api.field(v.tableIdentity())
+  refundRequestId: TableIdentity;
+
+  @Api.field(v.tableIdentity())
+  orderId: TableIdentity;
+
+  @Api.field(v.tableIdentity())
+  userId: TableIdentity;
+
+  @Api.field(z.enum(['created', 'succeeded', 'failed']))
+  state: TypeRefundAttemptState;
+
+  @Api.field(z.literal('USD'))
+  currency: 'USD';
+
+  @Api.field(z.number().int().nonnegative())
+  amountCents: number;
+
+  @Api.field(v.required(), v.min(1), v.max(100))
+  correlationId: string;
+
+  @Api.field(v.optional())
+  finalizedAt?: Date;
+}

package/vona/src/suite/a-commerce/modules/commerce-payment/src/entity/refundAudit.tsx

@@ -0,0 +1,47 @@
+import type { TableIdentity } from 'table-identity';
+import type { IDecoratorEntityOptions } from 'vona-module-a-orm';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Entity, EntityBase } from 'vona-module-a-orm';
+import { z } from 'zod';
+
+import type { TypeRefundAttemptState } from './refundAttempt.tsx';
+import type { TypeRefundRequestState } from './refundRequest.tsx';
+
+export interface IEntityOptionsRefundAudit extends IDecoratorEntityOptions {}
+
+@Entity<IEntityOptionsRefundAudit>('commercePaymentRefundAudit')
+export class EntityRefundAudit extends EntityBase {
+  @Api.field(v.tableIdentity())
+  refundRequestId: TableIdentity;
+
+  @Api.field(v.optional(), v.tableIdentity())
+  refundAttemptId?: TableIdentity;
+
+  @Api.field(v.tableIdentity())
+  orderId: TableIdentity;
+
+  @Api.field(v.tableIdentity())
+  userId: TableIdentity;
+
+  @Api.field(z.enum(['requested', 'approved', 'rejected', 'refunded', 'failed']))
+  toRefundState: TypeRefundRequestState;
+
+  @Api.field(v.optional(), z.enum(['created', 'succeeded', 'failed']))
+  attemptState?: TypeRefundAttemptState;
+
+  @Api.field(v.optional(), v.min(1), v.max(100))
+  idempotencyKey?: string;
+
+  @Api.field(v.required(), v.min(1), v.max(100))
+  correlationId: string;
+
+  @Api.field(v.required(), v.min(1), v.max(255))
+  reason: string;
+
+  @Api.field(v.optional(), v.tableIdentity())
+  actorId?: TableIdentity;
+
+  @Api.field(v.required())
+  processedAt: Date;
+}

package/vona/src/suite/a-commerce/modules/commerce-payment/src/entity/refundRequest.tsx

@@ -0,0 +1,43 @@
+import type { TableIdentity } from 'table-identity';
+import type { IDecoratorEntityOptions } from 'vona-module-a-orm';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Entity, EntityBase } from 'vona-module-a-orm';
+import { z } from 'zod';
+
+export type TypeRefundRequestState = 'requested' | 'approved' | 'rejected' | 'refunded' | 'failed';
+
+export interface IEntityOptionsRefundRequest extends IDecoratorEntityOptions {}
+
+@Entity<IEntityOptionsRefundRequest>('commercePaymentRefundRequest')
+export class EntityRefundRequest extends EntityBase {
+  @Api.field(v.tableIdentity())
+  orderId: TableIdentity;
+
+  @Api.field(v.tableIdentity())
+  userId: TableIdentity;
+
+  @Api.field(z.enum(['requested', 'approved', 'rejected', 'refunded', 'failed']))
+  state: TypeRefundRequestState;
+
+  @Api.field(z.literal('USD'))
+  currency: 'USD';
+
+  @Api.field(z.number().int().nonnegative())
+  amountCents: number;
+
+  @Api.field(v.required(), v.min(1), v.max(100))
+  correlationId: string;
+
+  @Api.field(v.required(), v.min(1), v.max(255))
+  reason: string;
+
+  @Api.field(v.optional(), v.tableIdentity())
+  reviewedBy?: TableIdentity;
+
+  @Api.field(v.optional())
+  reviewedAt?: Date;
+
+  @Api.field(v.optional())
+  finalizedAt?: Date;
+}

package/vona/src/suite/a-commerce/modules/commerce-payment/src/model/refundAttempt.ts

@@ -0,0 +1,10 @@
+import type { IDecoratorModelOptions } from 'vona-module-a-orm';
+
+import { BeanModelBase, Model } from 'vona-module-a-orm';
+
+import { EntityRefundAttempt } from '../entity/refundAttempt.tsx';
+
+export interface IModelOptionsRefundAttempt extends IDecoratorModelOptions<EntityRefundAttempt> {}
+
+@Model<IModelOptionsRefundAttempt>({ entity: EntityRefundAttempt })
+export class ModelRefundAttempt extends BeanModelBase<EntityRefundAttempt> {}

package/vona/src/suite/a-commerce/modules/commerce-payment/src/model/refundAudit.ts

@@ -0,0 +1,10 @@
+import type { IDecoratorModelOptions } from 'vona-module-a-orm';
+
+import { BeanModelBase, Model } from 'vona-module-a-orm';
+
+import { EntityRefundAudit } from '../entity/refundAudit.tsx';
+
+export interface IModelOptionsRefundAudit extends IDecoratorModelOptions<EntityRefundAudit> {}
+
+@Model<IModelOptionsRefundAudit>({ entity: EntityRefundAudit })
+export class ModelRefundAudit extends BeanModelBase<EntityRefundAudit> {}

package/vona/src/suite/a-commerce/modules/commerce-payment/src/model/refundRequest.ts

@@ -0,0 +1,10 @@
+import type { IDecoratorModelOptions } from 'vona-module-a-orm';
+
+import { BeanModelBase, Model } from 'vona-module-a-orm';
+
+import { EntityRefundRequest } from '../entity/refundRequest.tsx';
+
+export interface IModelOptionsRefundRequest extends IDecoratorModelOptions<EntityRefundRequest> {}
+
+@Model<IModelOptionsRefundRequest>({ entity: EntityRefundRequest })
+export class ModelRefundRequest extends BeanModelBase<EntityRefundRequest> {}

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

@@ -849,6 +849,10 @@ export * from '../dto/orderSummary.tsx';
 export * from '../dto/orderView.tsx';
 export * from '../dto/paymentOutcomeCreate.tsx';
 export * from '../dto/paymentOutcomeResult.tsx';
+export * from '../dto/refundOutcomeCreate.tsx';
+export * from '../dto/refundRequestCreate.tsx';
+export * from '../dto/refundResult.tsx';
+export * from '../dto/refundReview.tsx';
 export * from '../dto/shipmentView.tsx';
 export * from '../dto/stockAdjust.tsx';
 export * from '../dto/stockAuditCreate.tsx';
@@ -883,6 +887,10 @@ import type { IDtoOptionsOrderSummary } from '../dto/orderSummary.tsx';
 import type { IDtoOptionsOrderView } from '../dto/orderView.tsx';
 import type { IDtoOptionsPaymentOutcomeCreate } from '../dto/paymentOutcomeCreate.tsx';
 import type { IDtoOptionsPaymentOutcomeResult } from '../dto/paymentOutcomeResult.tsx';
+import type { IDtoOptionsRefundOutcomeCreate } from '../dto/refundOutcomeCreate.tsx';
+import type { IDtoOptionsRefundRequestCreate } from '../dto/refundRequestCreate.tsx';
+import type { IDtoOptionsRefundResult } from '../dto/refundResult.tsx';
+import type { IDtoOptionsRefundReview } from '../dto/refundReview.tsx';
 import type { IDtoOptionsShipmentView } from '../dto/shipmentView.tsx';
 import type { IDtoOptionsStockAdjust } from '../dto/stockAdjust.tsx';
 import type { IDtoOptionsStockAuditCreate } from '../dto/stockAuditCreate.tsx';
@@ -921,6 +929,10 @@ declare module 'vona-module-a-web' {
 'commerce-trade:orderView': IDtoOptionsOrderView;
 'commerce-trade:paymentOutcomeCreate': IDtoOptionsPaymentOutcomeCreate;
 'commerce-trade:paymentOutcomeResult': IDtoOptionsPaymentOutcomeResult;
+'commerce-trade:refundOutcomeCreate': IDtoOptionsRefundOutcomeCreate;
+'commerce-trade:refundRequestCreate': IDtoOptionsRefundRequestCreate;
+'commerce-trade:refundResult': IDtoOptionsRefundResult;
+'commerce-trade:refundReview': IDtoOptionsRefundReview;
 'commerce-trade:shipmentView': IDtoOptionsShipmentView;
 'commerce-trade:stockAdjust': IDtoOptionsStockAdjust;
 'commerce-trade:stockAuditCreate': IDtoOptionsStockAuditCreate;
@@ -964,6 +976,10 @@ import type { DtoOrderSummary } from '../dto/orderSummary.tsx';
 import type { DtoOrderView } from '../dto/orderView.tsx';
 import type { DtoPaymentOutcomeCreate } from '../dto/paymentOutcomeCreate.tsx';
 import type { DtoPaymentOutcomeResult } from '../dto/paymentOutcomeResult.tsx';
+import type { DtoRefundOutcomeCreate } from '../dto/refundOutcomeCreate.tsx';
+import type { DtoRefundRequestCreate } from '../dto/refundRequestCreate.tsx';
+import type { DtoRefundResult } from '../dto/refundResult.tsx';
+import type { DtoRefundReview } from '../dto/refundReview.tsx';
 import type { DtoShipmentView } from '../dto/shipmentView.tsx';
 import type { DtoStockAdjust } from '../dto/stockAdjust.tsx';
 import type { DtoStockAuditCreate } from '../dto/stockAuditCreate.tsx';
@@ -1060,6 +1076,22 @@ declare module 'vona-module-commerce-trade' {
       fields?: TypeEntityOptionsFields<DtoPaymentOutcomeResult, IDtoOptionsPaymentOutcomeResult[TypeSymbolKeyFieldsMore]>;
     }
 
+    export interface IDtoOptionsRefundOutcomeCreate {
+      fields?: TypeEntityOptionsFields<DtoRefundOutcomeCreate, IDtoOptionsRefundOutcomeCreate[TypeSymbolKeyFieldsMore]>;
+    }
+
+    export interface IDtoOptionsRefundRequestCreate {
+      fields?: TypeEntityOptionsFields<DtoRefundRequestCreate, IDtoOptionsRefundRequestCreate[TypeSymbolKeyFieldsMore]>;
+    }
+
+    export interface IDtoOptionsRefundResult {
+      fields?: TypeEntityOptionsFields<DtoRefundResult, IDtoOptionsRefundResult[TypeSymbolKeyFieldsMore]>;
+    }
+
+    export interface IDtoOptionsRefundReview {
+      fields?: TypeEntityOptionsFields<DtoRefundReview, IDtoOptionsRefundReview[TypeSymbolKeyFieldsMore]>;
+    }
+
     export interface IDtoOptionsShipmentView {
       fields?: TypeEntityOptionsFields<DtoShipmentView, IDtoOptionsShipmentView[TypeSymbolKeyFieldsMore]>;
     }
@@ -1267,6 +1299,10 @@ declare module 'vona-module-a-web' {
 export interface IApiPathPostRecord{
         '/commerce/trade/cart/items': undefined;
 '/commerce/trade/checkout': undefined;
+'/commerce/trade/order/:id/requestRefund': undefined;
+'/commerce/trade/order/:id/approveRefund': undefined;
+'/commerce/trade/order/:id/rejectRefund': undefined;
+'/commerce/trade/order/:id/refundOutcome': undefined;
 '/commerce/trade/order/:id/ship': undefined;
 '/commerce/trade/payment/:attemptId/outcome': undefined;
 '/commerce/trade/stockBalance/adjustStock': undefined;

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

@@ -16,6 +16,10 @@ import { DtoOrderSelectReq } from '../dto/orderSelectReq.tsx';
 import { DtoOrderSelectRes } from '../dto/orderSelectRes.tsx';
 import { DtoOrderShip } from '../dto/orderShip.tsx';
 import { DtoOrderView } from '../dto/orderView.tsx';
+import { DtoRefundOutcomeCreate } from '../dto/refundOutcomeCreate.tsx';
+import { DtoRefundRequestCreate } from '../dto/refundRequestCreate.tsx';
+import { DtoRefundResult } from '../dto/refundResult.tsx';
+import { DtoRefundReview } from '../dto/refundReview.tsx';
 import { DtoShipmentView } from '../dto/shipmentView.tsx';
 
 export interface IControllerOptionsOrder extends IDecoratorControllerOptions {}
@@ -39,6 +43,45 @@ export class ControllerOrder extends BeanBase {
     return await this.scope.service.order.viewMine(id);
   }
 
+  @Web.post(':id/requestRefund')
+  @Api.body(DtoRefundResult)
+  async requestRefund(
+    @Arg.param('id', v.tableIdentity()) id: TableIdentity,
+    @Arg.body() command: DtoRefundRequestCreate,
+  ): Promise<DtoRefundResult> {
+    return await this.scope.service.order.requestRefund(id, command);
+  }
+
+  @Web.post(':id/approveRefund')
+  @Api.body(DtoRefundResult)
+  @Passport.systemAdmin()
+  async approveRefund(
+    @Arg.param('id', v.tableIdentity()) id: TableIdentity,
+    @Arg.body() command: DtoRefundReview,
+  ): Promise<DtoRefundResult> {
+    return await this.scope.service.order.approveRefund(id, command);
+  }
+
+  @Web.post(':id/rejectRefund')
+  @Api.body(DtoRefundResult)
+  @Passport.systemAdmin()
+  async rejectRefund(
+    @Arg.param('id', v.tableIdentity()) id: TableIdentity,
+    @Arg.body() command: DtoRefundReview,
+  ): Promise<DtoRefundResult> {
+    return await this.scope.service.order.rejectRefund(id, command);
+  }
+
+  @Web.post(':id/refundOutcome')
+  @Api.body(DtoRefundResult)
+  @Passport.systemAdmin()
+  async refundOutcome(
+    @Arg.param('id', v.tableIdentity()) id: TableIdentity,
+    @Arg.body() command: DtoRefundOutcomeCreate,
+  ): Promise<DtoRefundResult> {
+    return await this.scope.service.order.applyRefundOutcome(id, command);
+  }
+
   @Web.post(':id/ship')
   @Api.body(DtoShipmentView)
   @Passport.systemAdmin()

package/vona/src/suite/a-commerce/modules/commerce-trade/src/dto/orderDetail.tsx

@@ -40,8 +40,29 @@ export class DtoOrderDetail {
   @Api.field(v.tableIdentity())
   id: TableIdentity;
 
-  @Api.field(z.enum(['awaiting_payment', 'paid', 'shipped', 'cancelled', 'expired']))
-  state: 'awaiting_payment' | 'paid' | 'shipped' | 'cancelled' | 'expired';
+  @Api.field(
+    z.enum([
+      'awaiting_payment',
+      'paid',
+      'refund_requested',
+      'refund_approved',
+      'refund_rejected',
+      'shipped',
+      'refunded',
+      'cancelled',
+      'expired',
+    ]),
+  )
+  state:
+    | 'awaiting_payment'
+    | 'paid'
+    | 'refund_requested'
+    | 'refund_approved'
+    | 'refund_rejected'
+    | 'shipped'
+    | 'refunded'
+    | 'cancelled'
+    | 'expired';
 
   @Api.field(z.literal('USD'))
   currency: 'USD';

package/vona/src/suite/a-commerce/modules/commerce-trade/src/dto/orderSelectResItem.tsx

@@ -30,6 +30,9 @@ export class DtoOrderSelectResItem extends $Dto.get(() => ModelOrder) {
         ZovaRender.tableActionRow('commerce-trade:actionShip', {
           permission: { public: true },
         }),
+        ZovaRender.tableActionRow('commerce-trade:actionRefund', {
+          permission: { public: true },
+        }),
         ZovaRender.tableActionRow('basic-table:actionView'),
       ],
     }),

package/vona/src/suite/a-commerce/modules/commerce-trade/src/dto/orderSummary.tsx

@@ -12,8 +12,29 @@ export class DtoOrderSummary {
   @Api.field(v.tableIdentity())
   id: TableIdentity;
 
-  @Api.field(z.enum(['awaiting_payment', 'paid', 'shipped', 'cancelled', 'expired']))
-  state: 'awaiting_payment' | 'paid' | 'shipped' | 'cancelled' | 'expired';
+  @Api.field(
+    z.enum([
+      'awaiting_payment',
+      'paid',
+      'refund_requested',
+      'refund_approved',
+      'refund_rejected',
+      'shipped',
+      'refunded',
+      'cancelled',
+      'expired',
+    ]),
+  )
+  state:
+    | 'awaiting_payment'
+    | 'paid'
+    | 'refund_requested'
+    | 'refund_approved'
+    | 'refund_rejected'
+    | 'shipped'
+    | 'refunded'
+    | 'cancelled'
+    | 'expired';
 
   @Api.field(z.literal('USD'))
   currency: 'USD';

package/vona/src/suite/a-commerce/modules/commerce-trade/src/dto/refundOutcomeCreate.tsx

@@ -0,0 +1,16 @@
+import type { IDecoratorDtoOptions } from 'vona-module-a-web';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Dto } from 'vona-module-a-web';
+import { z } from 'zod';
+
+export interface IDtoOptionsRefundOutcomeCreate extends IDecoratorDtoOptions {}
+
+@Dto<IDtoOptionsRefundOutcomeCreate>()
+export class DtoRefundOutcomeCreate {
+  @Api.field(z.enum(['succeeded', 'failed']))
+  outcome: 'succeeded' | 'failed';
+
+  @Api.field(v.required(), v.min(1), v.max(100))
+  idempotencyKey: string;
+}

package/vona/src/suite/a-commerce/modules/commerce-trade/src/dto/refundRequestCreate.tsx

@@ -0,0 +1,15 @@
+import type { IDecoratorDtoOptions } from 'vona-module-a-web';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Dto } from 'vona-module-a-web';
+
+export interface IDtoOptionsRefundRequestCreate extends IDecoratorDtoOptions {}
+
+@Dto<IDtoOptionsRefundRequestCreate>()
+export class DtoRefundRequestCreate {
+  @Api.field(v.required(), v.min(1), v.max(255))
+  reason: string;
+
+  @Api.field(v.required(), v.min(1), v.max(100))
+  idempotencyKey: string;
+}

package/vona/src/suite/a-commerce/modules/commerce-trade/src/dto/refundResult.tsx

@@ -0,0 +1,35 @@
+import type { TableIdentity } from 'table-identity';
+import type { IDecoratorDtoOptions } from 'vona-module-a-web';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Dto } from 'vona-module-a-web';
+import { z } from 'zod';
+
+export interface IDtoOptionsRefundResult extends IDecoratorDtoOptions {}
+
+@Dto<IDtoOptionsRefundResult>()
+export class DtoRefundResult {
+  @Api.field(v.tableIdentity())
+  orderId: TableIdentity;
+
+  @Api.field(v.tableIdentity())
+  refundRequestId: TableIdentity;
+
+  @Api.field(v.optional(), v.tableIdentity())
+  refundAttemptId?: TableIdentity;
+
+  @Api.field(z.enum(['paid', 'refund_requested', 'refund_approved', 'refund_rejected', 'refunded']))
+  orderState: 'paid' | 'refund_requested' | 'refund_approved' | 'refund_rejected' | 'refunded';
+
+  @Api.field(z.enum(['requested', 'approved', 'rejected', 'refunded', 'failed']))
+  refundState: 'requested' | 'approved' | 'rejected' | 'refunded' | 'failed';
+
+  @Api.field(v.optional(), z.enum(['created', 'succeeded', 'failed']))
+  refundAttemptState?: 'created' | 'succeeded' | 'failed';
+
+  @Api.field(z.literal('USD'))
+  currency: 'USD';
+
+  @Api.field(z.number().int().nonnegative())
+  amountCents: number;
+}

package/vona/src/suite/a-commerce/modules/commerce-trade/src/dto/refundReview.tsx

@@ -0,0 +1,15 @@
+import type { IDecoratorDtoOptions } from 'vona-module-a-web';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Dto } from 'vona-module-a-web';
+
+export interface IDtoOptionsRefundReview extends IDecoratorDtoOptions {}
+
+@Dto<IDtoOptionsRefundReview>()
+export class DtoRefundReview {
+  @Api.field(v.required(), v.min(1), v.max(255))
+  reason: string;
+
+  @Api.field(v.required(), v.min(1), v.max(100))
+  idempotencyKey: string;
+}

package/vona/src/suite/a-commerce/modules/commerce-trade/src/entity/orderAudit.tsx

@@ -7,7 +7,17 @@ import { z } from 'zod';
 
 import type { TypeOrderState } from './order.tsx';
 
-export type TypeOrderAuditOperation = 'created' | 'paid' | 'cancelled' | 'expired' | 'shipped';
+export type TypeOrderAuditOperation =
+  | 'created'
+  | 'paid'
+  | 'cancelled'
+  | 'expired'
+  | 'shipped'
+  | 'refund_requested'
+  | 'refund_approved'
+  | 'refund_rejected'
+  | 'refund_failed'
+  | 'refunded';
 
 export interface IEntityOptionsOrderAudit extends IDecoratorEntityOptions {}
 
@@ -16,20 +26,52 @@ export class EntityOrderAudit extends EntityBase {
   @Api.field(v.tableIdentity())
   orderId: TableIdentity;
 
-  @Api.field(z.enum(['created', 'paid', 'cancelled', 'expired', 'shipped']))
+  @Api.field(
+    z.enum([
+      'created',
+      'paid',
+      'cancelled',
+      'expired',
+      'shipped',
+      'refund_requested',
+      'refund_approved',
+      'refund_rejected',
+      'refund_failed',
+      'refunded',
+    ]),
+  )
   operation: TypeOrderAuditOperation;
 
-  @Api.field(v.optional(), z.enum(['awaiting_payment', 'paid', 'cancelled', 'expired', 'shipped']))
-  fromState?: Extract<
-    TypeOrderState,
-    'awaiting_payment' | 'paid' | 'cancelled' | 'expired' | 'shipped'
-  >;
-
-  @Api.field(z.enum(['awaiting_payment', 'paid', 'cancelled', 'expired', 'shipped']))
-  toState: Extract<
-    TypeOrderState,
-    'awaiting_payment' | 'paid' | 'cancelled' | 'expired' | 'shipped'
-  >;
+  @Api.field(
+    v.optional(),
+    z.enum([
+      'awaiting_payment',
+      'paid',
+      'refund_requested',
+      'refund_approved',
+      'refund_rejected',
+      'shipped',
+      'refunded',
+      'cancelled',
+      'expired',
+    ]),
+  )
+  fromState?: TypeOrderState;
+
+  @Api.field(
+    z.enum([
+      'awaiting_payment',
+      'paid',
+      'refund_requested',
+      'refund_approved',
+      'refund_rejected',
+      'shipped',
+      'refunded',
+      'cancelled',
+      'expired',
+    ]),
+  )
+  toState: TypeOrderState;
 
   @Api.field(v.optional(), v.tableIdentity())
   actorId?: TableIdentity;