@aepstore-dev/contracts 1.18.1 → 1.20.0

package/proto/payments.proto

@@ -1,203 +1,203 @@
-syntax = "proto3";
-
-package payments.v1;
-
-// 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);
-    rpc GetMyPurchases(GetMyPurchasesRequest) returns (PurchasesListResponse);
-    rpc GetPurchase(GetPurchaseRequest) returns (Purchase);
-    rpc RefundPurchase(RefundPurchaseRequest) returns (Purchase);
-
-    // ----- 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 / topup
-// ---------------------------------------------------------------------------
-message Purchase {
-    string id = 1;
-    string product_id = 2;
-    string product_name = 3;
-    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;
-    string product_id = 2;
-    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; // empty when paid from balance (instant)
-    string status = 4;           // PENDING (redirect) | COMPLETED (balance)
-}
-
-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; }
-
-// ---------------------------------------------------------------------------
-// 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;
-    string type = 2;  // optional filter (TOPUP|PURCHASE|SALE_CLEAR|WITHDRAWAL|REFUND|ADJUSTMENT)
-    int32 page = 3;
-    int32 limit = 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; }
-
-// ---------------------------------------------------------------------------
-// Withdrawals
-// ---------------------------------------------------------------------------
-message Withdrawal {
-    string id = 1;
-    string seller_id = 2;
-    string amount = 3;
-    string status = 4;     // PENDING | PROCESSING | COMPLETED | REJECTED
-    string method = 5;
-    string details = 6;
-    string comment = 7;
-    string processed_by = 8;
-    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; }
-
-// ---------------------------------------------------------------------------
-// Webhook
-// ---------------------------------------------------------------------------
-message PaymentEventRequest { string event = 1; string payment_id = 2; }
-
-// ---------------------------------------------------------------------------
-// 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
-}
+syntax = "proto3";
+
+package payments.v1;
+
+// 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);
+    rpc GetMyPurchases(GetMyPurchasesRequest) returns (PurchasesListResponse);
+    rpc GetPurchase(GetPurchaseRequest) returns (Purchase);
+    rpc RefundPurchase(RefundPurchaseRequest) returns (Purchase);
+
+    // ----- 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 / topup
+// ---------------------------------------------------------------------------
+message Purchase {
+    string id = 1;
+    string product_id = 2;
+    string product_name = 3;
+    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;
+    string product_id = 2;
+    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; // empty when paid from balance (instant)
+    string status = 4;           // PENDING (redirect) | COMPLETED (balance)
+}
+
+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; }
+
+// ---------------------------------------------------------------------------
+// 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;
+    string type = 2;  // optional filter (TOPUP|PURCHASE|SALE_CLEAR|WITHDRAWAL|REFUND|ADJUSTMENT)
+    int32 page = 3;
+    int32 limit = 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; }
+
+// ---------------------------------------------------------------------------
+// Withdrawals
+// ---------------------------------------------------------------------------
+message Withdrawal {
+    string id = 1;
+    string seller_id = 2;
+    string amount = 3;
+    string status = 4;     // PENDING | PROCESSING | COMPLETED | REJECTED
+    string method = 5;
+    string details = 6;
+    string comment = 7;
+    string processed_by = 8;
+    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; }
+
+// ---------------------------------------------------------------------------
+// Webhook
+// ---------------------------------------------------------------------------
+message PaymentEventRequest { string event = 1; string payment_id = 2; }
+
+// ---------------------------------------------------------------------------
+// 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
+}