feat: add wallet settlement audit flow

packages/contracts/src/index.ts

@@ -287,6 +287,7 @@ export interface GatewayUser {
   roles?: string[];
   authProfile?: Record<string, unknown>;
   metadata?: Record<string, unknown>;
+  walletAccounts?: GatewayWalletAccount[];
   status: 'active' | 'disabled' | 'locked' | 'deleted' | string;
   lastLoginAt?: string;
   syncedAt?: string;
@@ -499,7 +500,7 @@ export interface GatewayWalletTransaction {
   gatewayTenantId?: string;
   gatewayUserId?: string;
   direction: 'credit' | 'debit' | 'freeze' | 'unfreeze' | string;
-  transactionType: 'recharge' | 'billing' | 'refund' | 'adjustment' | string;
+  transactionType: 'recharge' | 'grant' | 'admin_adjust' | 'task_billing' | 'refund' | 'reserve' | 'release' | string;
   amount: number;
   balanceBefore: number;
   balanceAfter: number;
@@ -510,6 +511,42 @@ export interface GatewayWalletTransaction {
   createdAt: string;
 }
 
+export interface WalletBalanceAdjustmentRequest {
+  currency?: string;
+  balance: number;
+  reason: string;
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface WalletAdjustmentResponse {
+  account: GatewayWalletAccount;
+  before: GatewayWalletAccount;
+  transaction: GatewayWalletTransaction;
+  auditLog: GatewayAuditLog;
+}
+
+export interface GatewayAuditLog {
+  id: string;
+  category: string;
+  action: string;
+  actorGatewayUserId?: string;
+  actorUserId?: string;
+  actorUsername?: string;
+  actorSource?: string;
+  actorRoles?: string[];
+  targetType: string;
+  targetId: string;
+  targetGatewayUserId?: string;
+  targetGatewayTenantId?: string;
+  requestIp?: string;
+  userAgent?: string;
+  beforeState?: Record<string, unknown>;
+  afterState?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+
 export interface GatewayRechargeOrder {
   id: string;
   gatewayTenantId?: string;