@aepstore-dev/contracts 1.12.0 → 1.13.0

package/gen/payments.ts

@@ -16,52 +16,50 @@ export interface Ok {
 
 /**
  * ---------------------------------------------------------------------------
- * Purchase / checkout
+ * Purchase / checkout / topup
  * ---------------------------------------------------------------------------
  */
 export interface Purchase {
   id: string;
   productId: string;
   productName: string;
-  /** buyer */
   userId: string;
-  /** Decimal as string */
   price: string;
   /** PENDING | COMPLETED | FAILED | REFUNDED */
   status: string;
-  /** YooKassa payment id */
   paymentId: string;
-  /** snapshot, Decimal as string */
+  /** BALANCE | YOOKASSA */
+  paymentMethod: string;
   commissionPercent: string;
-  /** snapshot, Decimal as string */
   sellerAmount: string;
   createdAt: string;
   completedAt: string;
 }
 
+export interface TopupRequest {
+  userId: string;
+  /** >= 10.00 */
+  amount: string;
+  returnUrl: string;
+}
+
 export interface CreateCheckoutRequest {
-  /** buyer */
   userId: string;
   productId: string;
-  /** optional override; where YooKassa returns the buyer */
+  /** BALANCE | YOOKASSA (default YOOKASSA) */
+  paymentMethod: string;
   returnUrl: string;
 }
 
 export interface CheckoutResponse {
   purchaseId: string;
   paymentId: string;
-  /** redirect the buyer here */
+  /** empty when paid from balance (instant) */
   confirmationUrl: string;
+  /** PENDING (redirect) | COMPLETED (balance) */
   status: string;
 }
 
-export interface PaymentEventRequest {
-  /** payment.succeeded | payment.canceled | refund.succeeded */
-  event: string;
-  /** YooKassa payment object id (re-fetched & verified by the service) */
-  paymentId: string;
-}
-
 export interface GetMyPurchasesRequest {
   userId: string;
   page: number;
@@ -77,13 +75,11 @@ export interface PurchasesListResponse {
 
 export interface GetPurchaseRequest {
   id: string;
-  /** requester (must be buyer or admin) */
   userId: string;
 }
 
 export interface RefundPurchaseRequest {
   purchaseId: string;
-  /** buyer (own) or admin */
   actorUserId: string;
   isAdmin: boolean;
   reason: string;
@@ -91,32 +87,64 @@ export interface RefundPurchaseRequest {
 
 /**
  * ---------------------------------------------------------------------------
- * Seller balance & withdrawals
+ * Wallet & statement
  * ---------------------------------------------------------------------------
  */
-export interface GetSellerBalanceRequest {
-  sellerId: string;
+export interface GetWalletRequest {
+  userId: string;
 }
 
-export interface SellerBalanceResponse {
-  /** withdrawable now (cleared past the grace window) */
-  available: string;
-  /** still in the hold window */
+export interface WalletResponse {
+  spending: string;
   pending: string;
-  /** reserved by non-rejected withdrawals */
-  withdrawn: string;
-  /** RUB */
+  payout: string;
+  /** spending + payout */
+  spendable: string;
+  /** payout */
+  withdrawable: string;
   currency: string;
-  /** completed, non-refunded sales count */
   lifetimeSales: number;
-  /** tier the NEXT sale would use */
   currentCommissionPercent: string;
 }
 
+export interface ListTransactionsRequest {
+  userId: string;
+  /** optional filter (TOPUP|PURCHASE|SALE_CLEAR|WITHDRAWAL|REFUND|ADJUSTMENT) */
+  type: string;
+  page: number;
+  limit: number;
+}
+
+export interface StatementEntry {
+  /** ledger entry id */
+  id: string;
+  txId: string;
+  /** tx type */
+  type: string;
+  /** which of the user's accounts */
+  accountKind: string;
+  /** DEBIT | CREDIT */
+  direction: string;
+  amount: string;
+  description: string;
+  createdAt: string;
+}
+
+export interface TransactionsListResponse {
+  items: StatementEntry[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * Withdrawals
+ * ---------------------------------------------------------------------------
+ */
 export interface Withdrawal {
   id: string;
   sellerId: string;
-  /** Decimal as string */
   amount: string;
   /** PENDING | PROCESSING | COMPLETED | REJECTED */
   status: string;
@@ -130,14 +158,12 @@ export interface Withdrawal {
 
 export interface RequestWithdrawalRequest {
   sellerId: string;
-  /** Decimal as string */
   amount: string;
   method: string;
   details: string;
 }
 
 export interface ListWithdrawalsRequest {
-  /** empty = all (admin only) */
   sellerId: string;
   status: string;
   page: number;
@@ -154,27 +180,153 @@ export interface WithdrawalsListResponse {
 export interface ProcessWithdrawalRequest {
   withdrawalId: string;
   adminId: string;
-  /** approve (→PROCESSING) | complete (→COMPLETED) | reject (→REJECTED) */
   action: string;
   comment: string;
 }
 
+/**
+ * ---------------------------------------------------------------------------
+ * Webhook
+ * ---------------------------------------------------------------------------
+ */
+export interface PaymentEventRequest {
+  event: string;
+  paymentId: string;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * Admin
+ * ---------------------------------------------------------------------------
+ */
+export interface AdminOverviewRequest {
+  from: string;
+  to: string;
+}
+
+export interface AdminOverviewResponse {
+  /** platform commission earned (period) */
+  revenue: string;
+  /** gross merchandise value (period) */
+  gmv: string;
+  /** Σ all users' (pending+payout+spending) — what we owe */
+  liabilities: string;
+  /** money in transit at PSP */
+  pspClearing: string;
+  /** reserved for approved withdrawals */
+  payoutsPayable: string;
+  refundsTotal: string;
+  topupsTotal: string;
+  withdrawalsTotal: string;
+  salesCount: number;
+  currency: string;
+}
+
+export interface AdminListTransactionsRequest {
+  type: string;
+  userId: string;
+  accountKind: string;
+  from: string;
+  to: string;
+  page: number;
+  limit: number;
+}
+
+export interface AdminEntry {
+  accountId: string;
+  accountKind: string;
+  ownerId: string;
+  direction: string;
+  amount: string;
+}
+
+export interface AdminLedgerTx {
+  id: string;
+  type: string;
+  status: string;
+  refType: string;
+  refId: string;
+  description: string;
+  createdBy: string;
+  createdAt: string;
+  entries: AdminEntry[];
+}
+
+export interface AdminTransactionsListResponse {
+  items: AdminLedgerTx[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface GetUserFinanceRequest {
+  userId: string;
+}
+
+export interface AccountBalance {
+  kind: string;
+  balance: string;
+  currency: string;
+}
+
+export interface UserFinanceResponse {
+  wallet: WalletResponse | undefined;
+  accounts: AccountBalance[];
+  recent: StatementEntry[];
+}
+
+export interface CreateAdjustmentRequest {
+  adminId: string;
+  userId: string;
+  /** USER_SPENDING | USER_PAYOUT | USER_PENDING */
+  accountKind: string;
+  /** CREDIT (give) | DEBIT (take) */
+  direction: string;
+  amount: string;
+  reason: string;
+}
+
+export interface SalesAnalyticsRequest {
+  from: string;
+  to: string;
+  granularity: string;
+}
+
+export interface SalesPoint {
+  date: string;
+  salesCount: number;
+  gmv: string;
+  revenue: string;
+}
+
+export interface SellerStat {
+  sellerId: string;
+  username: string;
+  sales: number;
+  gmv: string;
+}
+
+export interface SalesAnalyticsResponse {
+  points: SalesPoint[];
+  topSellers: SellerStat[];
+  /** % refunded purchases */
+  refundRate: string;
+}
+
 export const PAYMENTS_V1_PACKAGE_NAME = "payments.v1";
 
 /**
- * Commerce: YooKassa acceptance + our hold/withdrawal model (D9).
- * Money values are Decimal-as-string (D7). Statuses are strings matching the DB
- * enum values (PENDING/COMPLETED/FAILED/REFUNDED for purchases;
- * PENDING/PROCESSING/COMPLETED/REJECTED for withdrawals) — kept as `string`
- * rather than proto enums to avoid value-name clashes inside one proto package.
+ * Commerce + double-entry wallet/ledger (D9 / D9.2). See payments-service/docs/FINANCE.md.
+ * Money = Decimal-as-string (D7). Statuses/enums as strings (avoid proto enum
+ * value-name clashes within one package).
  */
 
 export interface PaymentsServiceClient {
-  createCheckout(request: CreateCheckoutRequest): Observable<CheckoutResponse>;
+  /** ----- buyer ----- */
 
-  /** Gateway forwards a verified YooKassa webhook event here. */
+  topup(request: TopupRequest): Observable<CheckoutResponse>;
 
-  handlePaymentEvent(request: PaymentEventRequest): Observable<Ok>;
+  createCheckout(request: CreateCheckoutRequest): Observable<CheckoutResponse>;
 
   getMyPurchases(request: GetMyPurchasesRequest): Observable<PurchasesListResponse>;
 
@@ -182,32 +334,52 @@ export interface PaymentsServiceClient {
 
   refundPurchase(request: RefundPurchaseRequest): Observable<Purchase>;
 
-  getSellerBalance(request: GetSellerBalanceRequest): Observable<SellerBalanceResponse>;
+  /** ----- wallet ----- */
+
+  getWallet(request: GetWalletRequest): Observable<WalletResponse>;
+
+  listTransactions(request: ListTransactionsRequest): Observable<TransactionsListResponse>;
+
+  /** ----- withdrawals ----- */
 
   requestWithdrawal(request: RequestWithdrawalRequest): Observable<Withdrawal>;
 
   listWithdrawals(request: ListWithdrawalsRequest): Observable<WithdrawalsListResponse>;
 
   processWithdrawal(request: ProcessWithdrawalRequest): Observable<Withdrawal>;
+
+  /** ----- provider webhook (gateway forwards a verified event) ----- */
+
+  handlePaymentEvent(request: PaymentEventRequest): Observable<Ok>;
+
+  /** ----- admin ----- */
+
+  getAdminOverview(request: AdminOverviewRequest): Observable<AdminOverviewResponse>;
+
+  adminListTransactions(request: AdminListTransactionsRequest): Observable<AdminTransactionsListResponse>;
+
+  getUserFinance(request: GetUserFinanceRequest): Observable<UserFinanceResponse>;
+
+  createAdjustment(request: CreateAdjustmentRequest): Observable<Ok>;
+
+  getSalesAnalytics(request: SalesAnalyticsRequest): Observable<SalesAnalyticsResponse>;
 }
 
 /**
- * Commerce: YooKassa acceptance + our hold/withdrawal model (D9).
- * Money values are Decimal-as-string (D7). Statuses are strings matching the DB
- * enum values (PENDING/COMPLETED/FAILED/REFUNDED for purchases;
- * PENDING/PROCESSING/COMPLETED/REJECTED for withdrawals) — kept as `string`
- * rather than proto enums to avoid value-name clashes inside one proto package.
+ * Commerce + double-entry wallet/ledger (D9 / D9.2). See payments-service/docs/FINANCE.md.
+ * Money = Decimal-as-string (D7). Statuses/enums as strings (avoid proto enum
+ * value-name clashes within one package).
  */
 
 export interface PaymentsServiceController {
+  /** ----- buyer ----- */
+
+  topup(request: TopupRequest): Promise<CheckoutResponse> | Observable<CheckoutResponse> | CheckoutResponse;
+
   createCheckout(
     request: CreateCheckoutRequest,
   ): Promise<CheckoutResponse> | Observable<CheckoutResponse> | CheckoutResponse;
 
-  /** Gateway forwards a verified YooKassa webhook event here. */
-
-  handlePaymentEvent(request: PaymentEventRequest): Promise<Ok> | Observable<Ok> | Ok;
-
   getMyPurchases(
     request: GetMyPurchasesRequest,
   ): Promise<PurchasesListResponse> | Observable<PurchasesListResponse> | PurchasesListResponse;
@@ -216,9 +388,15 @@ export interface PaymentsServiceController {
 
   refundPurchase(request: RefundPurchaseRequest): Promise<Purchase> | Observable<Purchase> | Purchase;
 
-  getSellerBalance(
-    request: GetSellerBalanceRequest,
-  ): Promise<SellerBalanceResponse> | Observable<SellerBalanceResponse> | SellerBalanceResponse;
+  /** ----- wallet ----- */
+
+  getWallet(request: GetWalletRequest): Promise<WalletResponse> | Observable<WalletResponse> | WalletResponse;
+
+  listTransactions(
+    request: ListTransactionsRequest,
+  ): Promise<TransactionsListResponse> | Observable<TransactionsListResponse> | TransactionsListResponse;
+
+  /** ----- withdrawals ----- */
 
   requestWithdrawal(request: RequestWithdrawalRequest): Promise<Withdrawal> | Observable<Withdrawal> | Withdrawal;
 
@@ -227,20 +405,51 @@ export interface PaymentsServiceController {
   ): Promise<WithdrawalsListResponse> | Observable<WithdrawalsListResponse> | WithdrawalsListResponse;
 
   processWithdrawal(request: ProcessWithdrawalRequest): Promise<Withdrawal> | Observable<Withdrawal> | Withdrawal;
+
+  /** ----- provider webhook (gateway forwards a verified event) ----- */
+
+  handlePaymentEvent(request: PaymentEventRequest): Promise<Ok> | Observable<Ok> | Ok;
+
+  /** ----- admin ----- */
+
+  getAdminOverview(
+    request: AdminOverviewRequest,
+  ): Promise<AdminOverviewResponse> | Observable<AdminOverviewResponse> | AdminOverviewResponse;
+
+  adminListTransactions(
+    request: AdminListTransactionsRequest,
+  ): Promise<AdminTransactionsListResponse> | Observable<AdminTransactionsListResponse> | AdminTransactionsListResponse;
+
+  getUserFinance(
+    request: GetUserFinanceRequest,
+  ): Promise<UserFinanceResponse> | Observable<UserFinanceResponse> | UserFinanceResponse;
+
+  createAdjustment(request: CreateAdjustmentRequest): Promise<Ok> | Observable<Ok> | Ok;
+
+  getSalesAnalytics(
+    request: SalesAnalyticsRequest,
+  ): Promise<SalesAnalyticsResponse> | Observable<SalesAnalyticsResponse> | SalesAnalyticsResponse;
 }
 
 export function PaymentsServiceControllerMethods() {
   return function (constructor: Function) {
     const grpcMethods: string[] = [
+      "topup",
       "createCheckout",
-      "handlePaymentEvent",
       "getMyPurchases",
       "getPurchase",
       "refundPurchase",
-      "getSellerBalance",
+      "getWallet",
+      "listTransactions",
       "requestWithdrawal",
       "listWithdrawals",
       "processWithdrawal",
+      "handlePaymentEvent",
+      "getAdminOverview",
+      "adminListTransactions",
+      "getUserFinance",
+      "createAdjustment",
+      "getSalesAnalytics",
     ];
     for (const method of grpcMethods) {
       const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aepstore-dev/contracts",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Protobuf definitions for aepstore microservices",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/proto/payments.proto

@@ -2,108 +2,122 @@ syntax = "proto3";
 
 package payments.v1;
 
-// Commerce: YooKassa acceptance + our hold/withdrawal model (D9).
-// Money values are Decimal-as-string (D7). Statuses are strings matching the DB
-// enum values (PENDING/COMPLETED/FAILED/REFUNDED for purchases;
-// PENDING/PROCESSING/COMPLETED/REJECTED for withdrawals) — kept as `string`
-// rather than proto enums to avoid value-name clashes inside one proto package.
+// Commerce + double-entry wallet/ledger (D9 / D9.2). See payments-service/docs/FINANCE.md.
+// Money = Decimal-as-string (D7). Statuses/enums as strings (avoid proto enum
+// value-name clashes within one package).
 service PaymentsService {
+    // ----- buyer -----
+    rpc Topup(TopupRequest) returns (CheckoutResponse);
     rpc CreateCheckout(CreateCheckoutRequest) returns (CheckoutResponse);
-    // Gateway forwards a verified YooKassa webhook event here.
-    rpc HandlePaymentEvent(PaymentEventRequest) returns (Ok);
-
     rpc GetMyPurchases(GetMyPurchasesRequest) returns (PurchasesListResponse);
     rpc GetPurchase(GetPurchaseRequest) returns (Purchase);
     rpc RefundPurchase(RefundPurchaseRequest) returns (Purchase);
 
-    rpc GetSellerBalance(GetSellerBalanceRequest) returns (SellerBalanceResponse);
+    // ----- wallet -----
+    rpc GetWallet(GetWalletRequest) returns (WalletResponse);
+    rpc ListTransactions(ListTransactionsRequest) returns (TransactionsListResponse);
+
+    // ----- withdrawals -----
     rpc RequestWithdrawal(RequestWithdrawalRequest) returns (Withdrawal);
     rpc ListWithdrawals(ListWithdrawalsRequest) returns (WithdrawalsListResponse);
     rpc ProcessWithdrawal(ProcessWithdrawalRequest) returns (Withdrawal);
+
+    // ----- provider webhook (gateway forwards a verified event) -----
+    rpc HandlePaymentEvent(PaymentEventRequest) returns (Ok);
+
+    // ----- admin -----
+    rpc GetAdminOverview(AdminOverviewRequest) returns (AdminOverviewResponse);
+    rpc AdminListTransactions(AdminListTransactionsRequest) returns (AdminTransactionsListResponse);
+    rpc GetUserFinance(GetUserFinanceRequest) returns (UserFinanceResponse);
+    rpc CreateAdjustment(CreateAdjustmentRequest) returns (Ok);
+    rpc GetSalesAnalytics(SalesAnalyticsRequest) returns (SalesAnalyticsResponse);
 }
 
 message Ok { bool ok = 1; }
 
 // ---------------------------------------------------------------------------
-// Purchase / checkout
+// Purchase / checkout / topup
 // ---------------------------------------------------------------------------
 message Purchase {
     string id = 1;
     string product_id = 2;
     string product_name = 3;
-    string user_id = 4;          // buyer
-    string price = 5;            // Decimal as string
-    string status = 6;           // PENDING | COMPLETED | FAILED | REFUNDED
-    string payment_id = 7;       // YooKassa payment id
-    string commission_percent = 8; // snapshot, Decimal as string
-    string seller_amount = 9;    // snapshot, Decimal as string
-    string created_at = 10;
-    string completed_at = 11;
+    string user_id = 4;
+    string price = 5;
+    string status = 6;             // PENDING | COMPLETED | FAILED | REFUNDED
+    string payment_id = 7;
+    string payment_method = 8;     // BALANCE | YOOKASSA
+    string commission_percent = 9;
+    string seller_amount = 10;
+    string created_at = 11;
+    string completed_at = 12;
+}
+
+message TopupRequest {
+    string user_id = 1;
+    string amount = 2;       // >= 10.00
+    string return_url = 3;
 }
 
 message CreateCheckoutRequest {
-    string user_id = 1;     // buyer
+    string user_id = 1;
     string product_id = 2;
-    string return_url = 3;  // optional override; where YooKassa returns the buyer
+    string payment_method = 3; // BALANCE | YOOKASSA (default YOOKASSA)
+    string return_url = 4;
 }
 
 message CheckoutResponse {
     string purchase_id = 1;
     string payment_id = 2;
-    string confirmation_url = 3; // redirect the buyer here
-    string status = 4;
+    string confirmation_url = 3; // empty when paid from balance (instant)
+    string status = 4;           // PENDING (redirect) | COMPLETED (balance)
 }
 
-message PaymentEventRequest {
-    string event = 1;       // payment.succeeded | payment.canceled | refund.succeeded
-    string payment_id = 2;  // YooKassa payment object id (re-fetched & verified by the service)
-}
+message GetMyPurchasesRequest { string user_id = 1; int32 page = 2; int32 limit = 3; }
+message PurchasesListResponse { repeated Purchase items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
+message GetPurchaseRequest { string id = 1; string user_id = 2; }
+message RefundPurchaseRequest { string purchase_id = 1; string actor_user_id = 2; bool is_admin = 3; string reason = 4; }
 
-message GetMyPurchasesRequest {
+// ---------------------------------------------------------------------------
+// Wallet & statement
+// ---------------------------------------------------------------------------
+message GetWalletRequest { string user_id = 1; }
+message WalletResponse {
+    string spending = 1;
+    string pending = 2;
+    string payout = 3;
+    string spendable = 4;   // spending + payout
+    string withdrawable = 5; // payout
+    string currency = 6;
+    int32 lifetime_sales = 7;
+    string current_commission_percent = 8;
+}
+
+message ListTransactionsRequest {
     string user_id = 1;
-    int32 page = 2;
-    int32 limit = 3;
-}
-
-message PurchasesListResponse {
-    repeated Purchase items = 1;
-    int32 total = 2;
+    string type = 2;  // optional filter (TOPUP|PURCHASE|SALE_CLEAR|WITHDRAWAL|REFUND|ADJUSTMENT)
     int32 page = 3;
     int32 limit = 4;
 }
-
-message GetPurchaseRequest {
-    string id = 1;
-    string user_id = 2; // requester (must be buyer or admin)
-}
-
-message RefundPurchaseRequest {
-    string purchase_id = 1;
-    string actor_user_id = 2; // buyer (own) or admin
-    bool is_admin = 3;
-    string reason = 4;
+message StatementEntry {
+    string id = 1;            // ledger entry id
+    string tx_id = 2;
+    string type = 3;          // tx type
+    string account_kind = 4;  // which of the user's accounts
+    string direction = 5;     // DEBIT | CREDIT
+    string amount = 6;
+    string description = 7;
+    string created_at = 8;
 }
+message TransactionsListResponse { repeated StatementEntry items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
 
 // ---------------------------------------------------------------------------
-// Seller balance & withdrawals
+// Withdrawals
 // ---------------------------------------------------------------------------
-message GetSellerBalanceRequest {
-    string seller_id = 1;
-}
-
-message SellerBalanceResponse {
-    string available = 1;  // withdrawable now (cleared past the grace window)
-    string pending = 2;    // still in the hold window
-    string withdrawn = 3;  // reserved by non-rejected withdrawals
-    string currency = 4;   // RUB
-    int32 lifetime_sales = 5;          // completed, non-refunded sales count
-    string current_commission_percent = 6; // tier the NEXT sale would use
-}
-
 message Withdrawal {
     string id = 1;
     string seller_id = 2;
-    string amount = 3;     // Decimal as string
+    string amount = 3;
     string status = 4;     // PENDING | PROCESSING | COMPLETED | REJECTED
     string method = 5;
     string details = 6;
@@ -112,31 +126,78 @@ message Withdrawal {
     string processed_at = 9;
     string created_at = 10;
 }
+message RequestWithdrawalRequest { string seller_id = 1; string amount = 2; string method = 3; string details = 4; }
+message ListWithdrawalsRequest { string seller_id = 1; string status = 2; int32 page = 3; int32 limit = 4; }
+message WithdrawalsListResponse { repeated Withdrawal items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
+message ProcessWithdrawalRequest { string withdrawal_id = 1; string admin_id = 2; string action = 3; string comment = 4; }
 
-message RequestWithdrawalRequest {
-    string seller_id = 1;
-    string amount = 2;   // Decimal as string
-    string method = 3;
-    string details = 4;
-}
-
-message ListWithdrawalsRequest {
-    string seller_id = 1; // empty = all (admin only)
-    string status = 2;
-    int32 page = 3;
-    int32 limit = 4;
-}
-
-message WithdrawalsListResponse {
-    repeated Withdrawal items = 1;
-    int32 total = 2;
-    int32 page = 3;
-    int32 limit = 4;
-}
+// ---------------------------------------------------------------------------
+// Webhook
+// ---------------------------------------------------------------------------
+message PaymentEventRequest { string event = 1; string payment_id = 2; }
 
-message ProcessWithdrawalRequest {
-    string withdrawal_id = 1;
-    string admin_id = 2;
-    string action = 3;  // approve (→PROCESSING) | complete (→COMPLETED) | reject (→REJECTED)
-    string comment = 4;
+// ---------------------------------------------------------------------------
+// Admin
+// ---------------------------------------------------------------------------
+message AdminOverviewRequest { string from = 1; string to = 2; }
+message AdminOverviewResponse {
+    string revenue = 1;          // platform commission earned (period)
+    string gmv = 2;              // gross merchandise value (period)
+    string liabilities = 3;      // Σ all users' (pending+payout+spending) — what we owe
+    string psp_clearing = 4;     // money in transit at PSP
+    string payouts_payable = 5;  // reserved for approved withdrawals
+    string refunds_total = 6;
+    string topups_total = 7;
+    string withdrawals_total = 8;
+    int32 sales_count = 9;
+    string currency = 10;
+}
+
+message AdminListTransactionsRequest {
+    string type = 1;
+    string user_id = 2;
+    string account_kind = 3;
+    string from = 4;
+    string to = 5;
+    int32 page = 6;
+    int32 limit = 7;
+}
+message AdminEntry { string account_id = 1; string account_kind = 2; string owner_id = 3; string direction = 4; string amount = 5; }
+message AdminLedgerTx {
+    string id = 1;
+    string type = 2;
+    string status = 3;
+    string ref_type = 4;
+    string ref_id = 5;
+    string description = 6;
+    string created_by = 7;
+    string created_at = 8;
+    repeated AdminEntry entries = 9;
+}
+message AdminTransactionsListResponse { repeated AdminLedgerTx items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
+
+message GetUserFinanceRequest { string user_id = 1; }
+message AccountBalance { string kind = 1; string balance = 2; string currency = 3; }
+message UserFinanceResponse {
+    WalletResponse wallet = 1;
+    repeated AccountBalance accounts = 2;
+    repeated StatementEntry recent = 3;
+}
+
+message CreateAdjustmentRequest {
+    string admin_id = 1;
+    string user_id = 2;
+    string account_kind = 3; // USER_SPENDING | USER_PAYOUT | USER_PENDING
+    string direction = 4;    // CREDIT (give) | DEBIT (take)
+    string amount = 5;
+    string reason = 6;
+}
+
+message SalesAnalyticsRequest { string from = 1; string to = 2; string granularity = 3; } // day|week|month
+message SalesPoint { string date = 1; int32 sales_count = 2; string gmv = 3; string revenue = 4; }
+message SellerStat { string seller_id = 1; string username = 2; int32 sales = 3; string gmv = 4; }
+message SalesAnalyticsResponse {
+    repeated SalesPoint points = 1;
+    repeated SellerStat top_sellers = 2;
+    string refund_rate = 3; // % refunded purchases
 }