@aepstore-dev/contracts 1.35.0 → 1.37.0

package/gen/payments.ts

@@ -109,25 +109,83 @@ export interface WalletResponse {
 
 export interface ListTransactionsRequest {
   userId: string;
-  /** optional filter (TOPUP|PURCHASE|SALE_CLEAR|WITHDRAWAL|REFUND|ADJUSTMENT) */
+  /**
+   * Legacy low-level filter (one of LedgerTxType). Kept for backward
+   * compatibility — admin tooling still uses it directly.
+   */
   type: string;
   page: number;
   limit: number;
+  /**
+   * ↓ added for the wallet statement page (Round 3)
+   * UI-semantic filter mapped onto displayKind:
+   *   ALL | SALES | INCOME | OUTCOME | REFUND | WITHDRAWAL | PREMIUM
+   * SALES = the seller's earnings on this account (USER_PENDING credits from
+   * PURCHASE transactions); these stay separate from INCOME (TOPUP).
+   */
+  flow: string;
+  /**
+   * Period selection. `month` is the convenience form (YYYY-MM) used by the
+   * month dropdown; from/to override it for an arbitrary range.
+   */
+  month: string;
+  from: string;
+  to: string;
+  /**
+   * Filter wallet to purchases/refunds of a specific Product category. Has
+   * no effect on TOPUP/WITHDRAWAL/PREMIUM/ADJUSTMENT entries (they have no
+   * product).
+   */
+  productCategoryId: string;
+  /** sort_by ∈ { date | amount | type }. Default: date. */
+  sortBy: string;
+  /** order ∈ { asc | desc }. Default: desc. */
+  order: string;
 }
 
 export interface StatementEntry {
-  /** ledger entry id */
   id: string;
   txId: string;
-  /** tx type */
+  /** raw tx type (TOPUP|PURCHASE|...) */
   type: string;
-  /** which of the user's accounts */
   accountKind: string;
   /** DEBIT | CREDIT */
   direction: string;
   amount: string;
   description: string;
   createdAt: string;
+  /**
+   * ↓ added for the wallet statement page (Round 3)
+   * UI-friendly classification computed server-side:
+   *   TOPUP | PURCHASE | SALE | REFUND | PREMIUM | WITHDRAWAL | ADJUSTMENT
+   * SALE is the seller's view of someone else's PURCHASE (CREDIT to their
+   * USER_PENDING) — distinct from PURCHASE which is the buyer's DEBIT.
+   * PREMIUM is split out of PURCHASE/REFUND so the UI can show
+   * "Продление Premium" / refund-of-premium in their own filter bucket.
+   * SALE_CLEAR transactions are excluded from the wallet view — the maturity
+   * event is surfaced via sale_status on the original SALE row instead.
+   */
+  displayKind: string;
+  /** affected-account running balance, Decimal-as-string */
+  balanceAfter: string;
+  /** empty for non-product entries */
+  productId: string;
+  productName: string;
+  /** "Assets" | "Project File" | "Templates" */
+  productCategory: string;
+  /** optional thumbnail URL for richer rows */
+  productPreview: string;
+  /**
+   * Sale lifecycle. Populated only when display_kind=SALE.
+   *   PENDING — held in USER_PENDING, not yet withdrawable.
+   *   MATURED — SALE_CLEAR has fired; money is in USER_PAYOUT.
+   */
+  saleStatus: string;
+  /**
+   * ISO 8601 when the sale becomes withdrawable (sale_completed_at +
+   * GRACE_DAYS). Empty for non-sale rows.
+   */
+  maturesAt: string;
 }
 
 export interface TransactionsListResponse {
@@ -137,6 +195,18 @@ export interface TransactionsListResponse {
   limit: number;
 }
 
+export interface GetTransactionMonthsRequest {
+  userId: string;
+}
+
+export interface GetTransactionMonthsResponse {
+  /**
+   * Newest first. "YYYY-MM" strings; the dropdown renders them
+   * localized client-side.
+   */
+  months: string[];
+}
+
 /**
  * ---------------------------------------------------------------------------
  * Withdrawals
@@ -522,6 +592,8 @@ export interface PaymentsServiceClient {
 
   listTransactions(request: ListTransactionsRequest): Observable<TransactionsListResponse>;
 
+  getTransactionMonths(request: GetTransactionMonthsRequest): Observable<GetTransactionMonthsResponse>;
+
   /** ----- withdrawals ----- */
 
   requestWithdrawal(request: RequestWithdrawalRequest): Observable<Withdrawal>;
@@ -616,6 +688,10 @@ export interface PaymentsServiceController {
     request: ListTransactionsRequest,
   ): Promise<TransactionsListResponse> | Observable<TransactionsListResponse> | TransactionsListResponse;
 
+  getTransactionMonths(
+    request: GetTransactionMonthsRequest,
+  ): Promise<GetTransactionMonthsResponse> | Observable<GetTransactionMonthsResponse> | GetTransactionMonthsResponse;
+
   /** ----- withdrawals ----- */
 
   requestWithdrawal(request: RequestWithdrawalRequest): Promise<Withdrawal> | Observable<Withdrawal> | Withdrawal;
@@ -715,6 +791,7 @@ export function PaymentsServiceControllerMethods() {
       "refundPurchase",
       "getWallet",
       "listTransactions",
+      "getTransactionMonths",
       "requestWithdrawal",
       "listWithdrawals",
       "processWithdrawal",

package/package.json

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

package/proto/payments.proto

@@ -16,6 +16,7 @@ service PaymentsService {
     // ----- wallet -----
     rpc GetWallet(GetWalletRequest) returns (WalletResponse);
     rpc ListTransactions(ListTransactionsRequest) returns (TransactionsListResponse);
+    rpc GetTransactionMonths(GetTransactionMonthsRequest) returns (GetTransactionMonthsResponse);
 
     // ----- withdrawals -----
     rpc RequestWithdrawal(RequestWithdrawalRequest) returns (Withdrawal);
@@ -116,22 +117,72 @@ message WalletResponse {
 
 message ListTransactionsRequest {
     string user_id = 1;
-    string type = 2;  // optional filter (TOPUP|PURCHASE|SALE_CLEAR|WITHDRAWAL|REFUND|ADJUSTMENT)
+    // Legacy low-level filter (one of LedgerTxType). Kept for backward
+    // compatibility — admin tooling still uses it directly.
+    string type = 2;
     int32 page = 3;
     int32 limit = 4;
+    // ↓ added for the wallet statement page (Round 3)
+    // UI-semantic filter mapped onto displayKind:
+    //   ALL | SALES | INCOME | OUTCOME | REFUND | WITHDRAWAL | PREMIUM
+    // SALES = the seller's earnings on this account (USER_PENDING credits from
+    // PURCHASE transactions); these stay separate from INCOME (TOPUP).
+    string flow = 5;
+    // Period selection. `month` is the convenience form (YYYY-MM) used by the
+    // month dropdown; from/to override it for an arbitrary range.
+    string month = 6;
+    string from = 7;
+    string to = 8;
+    // Filter wallet to purchases/refunds of a specific Product category. Has
+    // no effect on TOPUP/WITHDRAWAL/PREMIUM/ADJUSTMENT entries (they have no
+    // product).
+    string product_category_id = 9;
+    // sort_by ∈ { date | amount | type }. Default: date.
+    string sort_by = 10;
+    // order ∈ { asc | desc }. Default: desc.
+    string order = 11;
 }
 message StatementEntry {
-    string id = 1;            // ledger entry id
+    string id = 1;
     string tx_id = 2;
-    string type = 3;          // tx type
-    string account_kind = 4;  // which of the user's accounts
+    string type = 3;          // raw tx type (TOPUP|PURCHASE|...)
+    string account_kind = 4;
     string direction = 5;     // DEBIT | CREDIT
     string amount = 6;
     string description = 7;
     string created_at = 8;
+    // ↓ added for the wallet statement page (Round 3)
+    // UI-friendly classification computed server-side:
+    //   TOPUP | PURCHASE | SALE | REFUND | PREMIUM | WITHDRAWAL | ADJUSTMENT
+    // SALE is the seller's view of someone else's PURCHASE (CREDIT to their
+    // USER_PENDING) — distinct from PURCHASE which is the buyer's DEBIT.
+    // PREMIUM is split out of PURCHASE/REFUND so the UI can show
+    // "Продление Premium" / refund-of-premium in their own filter bucket.
+    // SALE_CLEAR transactions are excluded from the wallet view — the maturity
+    // event is surfaced via sale_status on the original SALE row instead.
+    string display_kind = 9;
+    string balance_after = 10;       // affected-account running balance, Decimal-as-string
+    string product_id = 11;          // empty for non-product entries
+    string product_name = 12;
+    string product_category = 13;    // "Assets" | "Project File" | "Templates"
+    string product_preview = 14;     // optional thumbnail URL for richer rows
+    // Sale lifecycle. Populated only when display_kind=SALE.
+    //   PENDING — held in USER_PENDING, not yet withdrawable.
+    //   MATURED — SALE_CLEAR has fired; money is in USER_PAYOUT.
+    string sale_status = 15;
+    // ISO 8601 when the sale becomes withdrawable (sale_completed_at +
+    // GRACE_DAYS). Empty for non-sale rows.
+    string matures_at = 16;
 }
 message TransactionsListResponse { repeated StatementEntry items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
 
+message GetTransactionMonthsRequest { string user_id = 1; }
+message GetTransactionMonthsResponse {
+    // Newest first. "YYYY-MM" strings; the dropdown renders them
+    // localized client-side.
+    repeated string months = 1;
+}
+
 // ---------------------------------------------------------------------------
 // Withdrawals
 // ---------------------------------------------------------------------------