@aepstore-dev/contracts 1.68.0 → 1.69.0

package/gen/payments.ts

@@ -1,1048 +1,1048 @@
-// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
-// versions:
-//   protoc-gen-ts_proto  v2.10.1
-//   protoc               v7.35.0
-// source: payments.proto
-
-/* eslint-disable */
-import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
-import { Observable } from "rxjs";
-
-export const protobufPackage = "payments.v1";
-
-export interface Ok {
-  ok: boolean;
-}
-
-/**
- * ---------------------------------------------------------------------------
- * Purchase / checkout / topup
- * ---------------------------------------------------------------------------
- */
-export interface Purchase {
-  id: string;
-  productId: string;
-  productName: string;
-  userId: string;
-  /** settled RUB amount */
-  price: string;
-  /** PENDING | COMPLETED | FAILED | REFUNDED */
-  status: string;
-  paymentId: string;
-  /** BALANCE | YOOKASSA | CRYPTO */
-  paymentMethod: string;
-  commissionPercent: string;
-  sellerAmount: string;
-  createdAt: string;
-  completedAt: string;
-  /** FX snapshot at checkout (empty for legacy RUB purchases). */
-  listingCurrency: string;
-  /** Decimal as string, in listing_currency */
-  listingPrice: string;
-  /** listing→RUB rate used (Decimal as string) */
-  fxRate: string;
-}
-
-export interface TopupRequest {
-  userId: string;
-  /** >= 10.00 */
-  amount: string;
-  returnUrl: string;
-  /** YOOKASSA | SAVED_CARD | CRYPTO (default YOOKASSA) */
-  paymentMethod: string;
-  /** required when payment_method=SAVED_CARD */
-  savedCardId: string;
-}
-
-export interface CreateCheckoutRequest {
-  userId: string;
-  productId: string;
-  /** BALANCE | YOOKASSA | SAVED_CARD | CRYPTO (default YOOKASSA) */
-  paymentMethod: string;
-  returnUrl: string;
-  /**
-   * When payment_method=SAVED_CARD — required. ID of a SavedCard row owned
-   * by user_id. Ignored otherwise.
-   */
-  savedCardId: string;
-  /**
-   * When payment_method=YOOKASSA — optional. If true, save the card token
-   * after success; the bound card becomes available in /account/cards.
-   */
-  savePaymentMethod: boolean;
-}
-
-export interface BindCardRequest {
-  userId: string;
-  returnUrl: string;
-}
-
-export interface GetPaymentIntentRequest {
-  intentId: string;
-  /** ownership check */
-  userId: string;
-}
-
-export interface PaymentIntentStatus {
-  id: string;
-  userId: string;
-  /** TOPUP | PREMIUM */
-  purpose: string;
-  /** PENDING | COMPLETED | FAILED | CANCELED */
-  status: string;
-  amount: string;
-  currency: string;
-  /** set when purpose=PREMIUM (else empty) */
-  purchaseId: string;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface CheckoutResponse {
-  purchaseId: string;
-  paymentId: string;
-  /** empty when paid from balance (instant) */
-  confirmationUrl: string;
-  /** PENDING (redirect) | COMPLETED (balance) */
-  status: string;
-  /** poll via GetPaymentIntent for TOPUP / bind-card flows */
-  intentId: string;
-}
-
-export interface GetMyPurchasesRequest {
-  userId: string;
-  page: number;
-  limit: number;
-}
-
-export interface PurchasesListResponse {
-  items: Purchase[];
-  total: number;
-  page: number;
-  limit: number;
-}
-
-export interface GetPurchaseRequest {
-  id: string;
-  userId: string;
-}
-
-export interface RefundPurchaseRequest {
-  purchaseId: string;
-  actorUserId: string;
-  isAdmin: boolean;
-  reason: string;
-}
-
-/**
- * ---------------------------------------------------------------------------
- * Wallet & statement
- * ---------------------------------------------------------------------------
- */
-export interface GetWalletRequest {
-  userId: string;
-}
-
-export interface WalletResponse {
-  spending: string;
-  pending: string;
-  payout: string;
-  /** spending + payout */
-  spendable: string;
-  /** payout */
-  withdrawable: string;
-  currency: string;
-  lifetimeSales: number;
-  currentCommissionPercent: string;
-}
-
-export interface ListTransactionsRequest {
-  userId: string;
-  /**
-   * 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 {
-  id: string;
-  txId: string;
-  /** raw tx type (TOPUP|PURCHASE|...) */
-  type: string;
-  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 {
-  items: StatementEntry[];
-  total: number;
-  page: number;
-  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
- * ---------------------------------------------------------------------------
- */
-export interface Withdrawal {
-  id: string;
-  sellerId: string;
-  amount: string;
-  /** PENDING | PROCESSING | COMPLETED | REJECTED */
-  status: string;
-  method: string;
-  details: string;
-  comment: string;
-  processedBy: string;
-  processedAt: string;
-  createdAt: string;
-}
-
-export interface RequestWithdrawalRequest {
-  sellerId: string;
-  amount: string;
-  method: string;
-  details: string;
-}
-
-export interface ListWithdrawalsRequest {
-  sellerId: string;
-  status: string;
-  page: number;
-  limit: number;
-}
-
-export interface WithdrawalsListResponse {
-  items: Withdrawal[];
-  total: number;
-  page: number;
-  limit: number;
-}
-
-export interface ProcessWithdrawalRequest {
-  withdrawalId: string;
-  adminId: string;
-  action: string;
-  comment: string;
-}
-
-/**
- * ---------------------------------------------------------------------------
- * Webhook
- * ---------------------------------------------------------------------------
- */
-export interface PaymentEventRequest {
-  event: string;
-  paymentId: string;
-}
-
-export interface ProviderCallbackRequest {
-  /** yookassa | heleket | … */
-  provider: string;
-  /** exact raw JSON body as received (signature input) */
-  rawBody: string;
-}
-
-/**
- * ---------------------------------------------------------------------------
- * FX rates / payment methods
- * ---------------------------------------------------------------------------
- */
-export interface GetRatesRequest {
-}
-
-export interface FxRate {
-  /** USD | EUR */
-  currency: string;
-  /** RUB per 1 unit, Decimal as string */
-  rate: string;
-}
-
-export interface GetRatesResponse {
-  /** always RUB */
-  base: string;
-  /** YYYY-MM-DD the rates are for */
-  asOf: string;
-  rates: FxRate[];
-}
-
-export interface GetPaymentMethodsRequest {
-}
-
-export interface PaymentMethodInfo {
-  /** YOOKASSA | SAVED_CARD | CRYPTO | BALANCE */
-  method: string;
-  /** yookassa | heleket | '' (BALANCE) */
-  provider: string;
-  currencies: string[];
-}
-
-export interface GetPaymentMethodsResponse {
-  methods: PaymentMethodInfo[];
-}
-
-/**
- * ---------------------------------------------------------------------------
- * 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;
-}
-
-/**
- * ---------------------------------------------------------------------------
- * Premium
- * ---------------------------------------------------------------------------
- */
-export interface GetPremiumPlansRequest {
-}
-
-/**
- * One plan per (period). Prices are computed server-side from BASE_PRICE × months
- * × (1 − discount); kept here as canonical strings so the gateway has no math.
- */
-export interface PremiumPlan {
-  /** MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12 */
-  period: string;
-  months: number;
-  /** total to charge, Decimal-as-string */
-  price: string;
-  /** for UI "≈ X ₽/month" */
-  monthlyPrice: string;
-  discountPercent: string;
-  currency: string;
-}
-
-export interface PremiumPlansResponse {
-  plans: PremiumPlan[];
-  baseMonthlyPrice: string;
-}
-
-export interface PurchasePremiumRequest {
-  userId: string;
-  /** MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12 */
-  period: string;
-  /** BALANCE | YOOKASSA | SAVED_CARD (empty = smart default) */
-  paymentMethod: string;
-  /** YooKassa only */
-  returnUrl: string;
-  /**
-   * Save the YooKassa payment_method for future auto-renewals. Ignored for
-   * BALANCE. Kept for backwards compatibility; auto_renew=true implies save.
-   */
-  savePaymentMethod: boolean;
-  /** default false; requires off-session-capable method */
-  autoRenew: boolean;
-  /** optional for SAVED_CARD; empty = default card */
-  savedCardId: string;
-}
-
-export interface PurchasePremiumResponse {
-  /** PremiumPayment.id */
-  paymentId: string;
-  /** empty for BALANCE (instant) or YooKassa-issued */
-  confirmationUrl: string;
-  /** PENDING (redirect) | COMPLETED (balance) */
-  status: string;
-}
-
-export interface RunPremiumRenewalsRequest {
-  /** safety cap; default 100 */
-  maxBatch: number;
-}
-
-export interface RunPremiumRenewalsResponse {
-  attempted: number;
-  succeeded: number;
-  failed: number;
-}
-
-export interface SetPremiumPaymentMethodRequest {
-  userId: string;
-  /** BALANCE | YOOKASSA | SAVED_CARD */
-  method: string;
-  /** optional for SAVED_CARD; empty = default card */
-  savedCardId: string;
-}
-
-export interface PremiumPaymentMethodResponse {
-  /** BALANCE | YOOKASSA | SAVED_CARD */
-  method: string;
-  /** empty unless SAVED_CARD */
-  savedCardId: string;
-  autoRenew: boolean;
-}
-
-export interface PremiumPaymentRow {
-  id: string;
-  userId: string;
-  amount: string;
-  /** MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12 */
-  period: string;
-  /** BALANCE | YOOKASSA */
-  method: string;
-  /** PENDING | COMPLETED | FAILED | REFUNDED */
-  status: string;
-  isRenewal: boolean;
-  createdAt: string;
-  completedAt: string;
-  refundedAt: string;
-  refundedAmount: string;
-  /**
-   * Convenience: true if this payment is currently inside the 7-day refund
-   * window AND status == COMPLETED AND not already refunded.
-   */
-  refundable: boolean;
-}
-
-export interface RefundPremiumRequest {
-  userId: string;
-  paymentId: string;
-  /** optional */
-  reason: string;
-}
-
-export interface RefundPremiumResponse {
-  payment:
-    | PremiumPaymentRow
-    | undefined;
-  /** ISO 8601 after rollback */
-  newExpiresAt: string;
-  /** true when rollback put expiresAt <= now */
-  subscriptionRevoked: boolean;
-}
-
-export interface GetMyPremiumPaymentsRequest {
-  userId: string;
-  page: number;
-  limit: number;
-}
-
-export interface GetPremiumPaymentRequest {
-  userId: string;
-  paymentId: string;
-}
-
-export interface PremiumPaymentsListResponse {
-  items: PremiumPaymentRow[];
-  total: number;
-  page: number;
-  limit: number;
-}
-
-/**
- * ---------------------------------------------------------------------------
- * Saved cards (YooKassa payment_method tokens; we never see PAN)
- * ---------------------------------------------------------------------------
- */
-export interface SavedCard {
-  id: string;
-  /** "MIR" | "VISA" | "MASTERCARD" | "" */
-  brand: string;
-  /** "0000" etc, display-only */
-  last4: string;
-  expMonth: number;
-  expYear: number;
-  isDefault: boolean;
-  /** user-set label */
-  nickname: string;
-  createdAt: string;
-}
-
-export interface ListSavedCardsRequest {
-  userId: string;
-}
-
-export interface ListSavedCardsResponse {
-  items: SavedCard[];
-}
-
-export interface DeleteSavedCardRequest {
-  userId: string;
-  id: string;
-}
-
-export interface SetDefaultSavedCardRequest {
-  userId: string;
-  id: string;
-}
-
-export interface UpdateSavedCardRequest {
-  userId: string;
-  id: string;
-  /** empty = clear */
-  nickname: string;
-}
-
-/**
- * ---------------------------------------------------------------------------
- * Payout details (persistent default; per-withdrawal override still allowed)
- * ---------------------------------------------------------------------------
- */
-export interface UpdatePayoutDetailsRequest {
-  userId: string;
-  /** "card" | "sbp" | "bank" | "" (clear) */
-  method: string;
-  /** JSON string — payments-service treats opaquely */
-  details: string;
-}
-
-export interface UpdatePayoutDetailsResponse {
-  method: string;
-  details: string;
-}
-
-export interface GetPayoutDetailsRequest {
-  userId: string;
-}
-
-export const PAYMENTS_V1_PACKAGE_NAME = "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).
- */
-
-export interface PaymentsServiceClient {
-  /** ----- buyer ----- */
-
-  topup(request: TopupRequest): Observable<CheckoutResponse>;
-
-  createCheckout(request: CreateCheckoutRequest): Observable<CheckoutResponse>;
-
-  getMyPurchases(request: GetMyPurchasesRequest): Observable<PurchasesListResponse>;
-
-  getPurchase(request: GetPurchaseRequest): Observable<Purchase>;
-
-  refundPurchase(request: RefundPurchaseRequest): Observable<Purchase>;
-
-  /** ----- wallet ----- */
-
-  getWallet(request: GetWalletRequest): Observable<WalletResponse>;
-
-  listTransactions(request: ListTransactionsRequest): Observable<TransactionsListResponse>;
-
-  getTransactionMonths(request: GetTransactionMonthsRequest): Observable<GetTransactionMonthsResponse>;
-
-  /** ----- 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>;
-
-  /**
-   * Generalized per-provider callback (POST /payments/webhook/:provider).
-   * Carries the EXACT raw JSON body: signed providers (Heleket) hash the
-   * byte-exact payload, so re-serializing a parsed body would break the sign.
-   */
-
-  handleProviderCallback(request: ProviderCallbackRequest): Observable<Ok>;
-
-  /** ----- premium ----- */
-
-  getPremiumPlans(request: GetPremiumPlansRequest): Observable<PremiumPlansResponse>;
-
-  purchasePremium(request: PurchasePremiumRequest): Observable<PurchasePremiumResponse>;
-
-  setPremiumPaymentMethod(request: SetPremiumPaymentMethodRequest): Observable<PremiumPaymentMethodResponse>;
-
-  /**
-   * 7-day refund window from completedAt. Reverses ledger, calls YooKassa for
-   * card purchases, rolls back the subscription's expiresAt by the period.
-   */
-
-  refundPremium(request: RefundPremiumRequest): Observable<RefundPremiumResponse>;
-
-  getMyPremiumPayments(request: GetMyPremiumPaymentsRequest): Observable<PremiumPaymentsListResponse>;
-
-  getPremiumPayment(request: GetPremiumPaymentRequest): Observable<PremiumPaymentRow>;
-
-  /**
-   * Internal — InternalServiceGuard. tasks-service cron triggers due renewals;
-   * payments-service iterates ACTIVE subscriptions with autoRenew+savedCard.
-   */
-
-  runPremiumRenewals(request: RunPremiumRenewalsRequest): Observable<RunPremiumRenewalsResponse>;
-
-  /** ----- saved cards ----- */
-
-  listSavedCards(request: ListSavedCardsRequest): Observable<ListSavedCardsResponse>;
-
-  deleteSavedCard(request: DeleteSavedCardRequest): Observable<Ok>;
-
-  setDefaultSavedCard(request: SetDefaultSavedCardRequest): Observable<SavedCard>;
-
-  updateSavedCard(request: UpdateSavedCardRequest): Observable<SavedCard>;
-
-  /**
-   * Standalone "bind card" flow: creates a 1₽ YooKassa charge with
-   * save_payment_method=true; after the webhook the SavedCard row is
-   * persisted and the 1₽ credits USER_SPENDING so the user keeps it.
-   */
-
-  bindCard(request: BindCardRequest): Observable<CheckoutResponse>;
-
-  /**
-   * Poll an intent after returnUrl redirect: TOPUP/PREMIUM completion, bind-card
-   * completion. Ownership-checked by user_id.
-   */
-
-  getPaymentIntent(request: GetPaymentIntentRequest): Observable<PaymentIntentStatus>;
-
-  /**
-   * ----- FX / available methods (public, cached) -----
-   * Daily CBR rates (RUB base). Frontend uses this for the "≈" display hint;
-   * the authoritative charge amount is always computed server-side at checkout.
-   */
-
-  getRates(request: GetRatesRequest): Observable<GetRatesResponse>;
-
-  /**
-   * Payment methods derived from live provider capabilities — the client
-   * renders only what is actually available (e.g. CRYPTO appears once the
-   * Heleket merchant is configured).
-   */
-
-  getPaymentMethods(request: GetPaymentMethodsRequest): Observable<GetPaymentMethodsResponse>;
-
-  /** ----- payout details ----- */
-
-  updatePayoutDetails(request: UpdatePayoutDetailsRequest): Observable<UpdatePayoutDetailsResponse>;
-
-  getPayoutDetails(request: GetPayoutDetailsRequest): Observable<UpdatePayoutDetailsResponse>;
-
-  /** ----- 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 + 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;
-
-  getMyPurchases(
-    request: GetMyPurchasesRequest,
-  ): Promise<PurchasesListResponse> | Observable<PurchasesListResponse> | PurchasesListResponse;
-
-  getPurchase(request: GetPurchaseRequest): Promise<Purchase> | Observable<Purchase> | Purchase;
-
-  refundPurchase(request: RefundPurchaseRequest): Promise<Purchase> | Observable<Purchase> | Purchase;
-
-  /** ----- wallet ----- */
-
-  getWallet(request: GetWalletRequest): Promise<WalletResponse> | Observable<WalletResponse> | WalletResponse;
-
-  listTransactions(
-    request: ListTransactionsRequest,
-  ): Promise<TransactionsListResponse> | Observable<TransactionsListResponse> | TransactionsListResponse;
-
-  getTransactionMonths(
-    request: GetTransactionMonthsRequest,
-  ): Promise<GetTransactionMonthsResponse> | Observable<GetTransactionMonthsResponse> | GetTransactionMonthsResponse;
-
-  /** ----- withdrawals ----- */
-
-  requestWithdrawal(request: RequestWithdrawalRequest): Promise<Withdrawal> | Observable<Withdrawal> | Withdrawal;
-
-  listWithdrawals(
-    request: ListWithdrawalsRequest,
-  ): 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;
-
-  /**
-   * Generalized per-provider callback (POST /payments/webhook/:provider).
-   * Carries the EXACT raw JSON body: signed providers (Heleket) hash the
-   * byte-exact payload, so re-serializing a parsed body would break the sign.
-   */
-
-  handleProviderCallback(request: ProviderCallbackRequest): Promise<Ok> | Observable<Ok> | Ok;
-
-  /** ----- premium ----- */
-
-  getPremiumPlans(
-    request: GetPremiumPlansRequest,
-  ): Promise<PremiumPlansResponse> | Observable<PremiumPlansResponse> | PremiumPlansResponse;
-
-  purchasePremium(
-    request: PurchasePremiumRequest,
-  ): Promise<PurchasePremiumResponse> | Observable<PurchasePremiumResponse> | PurchasePremiumResponse;
-
-  setPremiumPaymentMethod(
-    request: SetPremiumPaymentMethodRequest,
-  ): Promise<PremiumPaymentMethodResponse> | Observable<PremiumPaymentMethodResponse> | PremiumPaymentMethodResponse;
-
-  /**
-   * 7-day refund window from completedAt. Reverses ledger, calls YooKassa for
-   * card purchases, rolls back the subscription's expiresAt by the period.
-   */
-
-  refundPremium(
-    request: RefundPremiumRequest,
-  ): Promise<RefundPremiumResponse> | Observable<RefundPremiumResponse> | RefundPremiumResponse;
-
-  getMyPremiumPayments(
-    request: GetMyPremiumPaymentsRequest,
-  ): Promise<PremiumPaymentsListResponse> | Observable<PremiumPaymentsListResponse> | PremiumPaymentsListResponse;
-
-  getPremiumPayment(
-    request: GetPremiumPaymentRequest,
-  ): Promise<PremiumPaymentRow> | Observable<PremiumPaymentRow> | PremiumPaymentRow;
-
-  /**
-   * Internal — InternalServiceGuard. tasks-service cron triggers due renewals;
-   * payments-service iterates ACTIVE subscriptions with autoRenew+savedCard.
-   */
-
-  runPremiumRenewals(
-    request: RunPremiumRenewalsRequest,
-  ): Promise<RunPremiumRenewalsResponse> | Observable<RunPremiumRenewalsResponse> | RunPremiumRenewalsResponse;
-
-  /** ----- saved cards ----- */
-
-  listSavedCards(
-    request: ListSavedCardsRequest,
-  ): Promise<ListSavedCardsResponse> | Observable<ListSavedCardsResponse> | ListSavedCardsResponse;
-
-  deleteSavedCard(request: DeleteSavedCardRequest): Promise<Ok> | Observable<Ok> | Ok;
-
-  setDefaultSavedCard(request: SetDefaultSavedCardRequest): Promise<SavedCard> | Observable<SavedCard> | SavedCard;
-
-  updateSavedCard(request: UpdateSavedCardRequest): Promise<SavedCard> | Observable<SavedCard> | SavedCard;
-
-  /**
-   * Standalone "bind card" flow: creates a 1₽ YooKassa charge with
-   * save_payment_method=true; after the webhook the SavedCard row is
-   * persisted and the 1₽ credits USER_SPENDING so the user keeps it.
-   */
-
-  bindCard(request: BindCardRequest): Promise<CheckoutResponse> | Observable<CheckoutResponse> | CheckoutResponse;
-
-  /**
-   * Poll an intent after returnUrl redirect: TOPUP/PREMIUM completion, bind-card
-   * completion. Ownership-checked by user_id.
-   */
-
-  getPaymentIntent(
-    request: GetPaymentIntentRequest,
-  ): Promise<PaymentIntentStatus> | Observable<PaymentIntentStatus> | PaymentIntentStatus;
-
-  /**
-   * ----- FX / available methods (public, cached) -----
-   * Daily CBR rates (RUB base). Frontend uses this for the "≈" display hint;
-   * the authoritative charge amount is always computed server-side at checkout.
-   */
-
-  getRates(request: GetRatesRequest): Promise<GetRatesResponse> | Observable<GetRatesResponse> | GetRatesResponse;
-
-  /**
-   * Payment methods derived from live provider capabilities — the client
-   * renders only what is actually available (e.g. CRYPTO appears once the
-   * Heleket merchant is configured).
-   */
-
-  getPaymentMethods(
-    request: GetPaymentMethodsRequest,
-  ): Promise<GetPaymentMethodsResponse> | Observable<GetPaymentMethodsResponse> | GetPaymentMethodsResponse;
-
-  /** ----- payout details ----- */
-
-  updatePayoutDetails(
-    request: UpdatePayoutDetailsRequest,
-  ): Promise<UpdatePayoutDetailsResponse> | Observable<UpdatePayoutDetailsResponse> | UpdatePayoutDetailsResponse;
-
-  getPayoutDetails(
-    request: GetPayoutDetailsRequest,
-  ): Promise<UpdatePayoutDetailsResponse> | Observable<UpdatePayoutDetailsResponse> | UpdatePayoutDetailsResponse;
-
-  /** ----- 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",
-      "getMyPurchases",
-      "getPurchase",
-      "refundPurchase",
-      "getWallet",
-      "listTransactions",
-      "getTransactionMonths",
-      "requestWithdrawal",
-      "listWithdrawals",
-      "processWithdrawal",
-      "handlePaymentEvent",
-      "handleProviderCallback",
-      "getPremiumPlans",
-      "purchasePremium",
-      "setPremiumPaymentMethod",
-      "refundPremium",
-      "getMyPremiumPayments",
-      "getPremiumPayment",
-      "runPremiumRenewals",
-      "listSavedCards",
-      "deleteSavedCard",
-      "setDefaultSavedCard",
-      "updateSavedCard",
-      "bindCard",
-      "getPaymentIntent",
-      "getRates",
-      "getPaymentMethods",
-      "updatePayoutDetails",
-      "getPayoutDetails",
-      "getAdminOverview",
-      "adminListTransactions",
-      "getUserFinance",
-      "createAdjustment",
-      "getSalesAnalytics",
-    ];
-    for (const method of grpcMethods) {
-      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
-      GrpcMethod("PaymentsService", method)(constructor.prototype[method], method, descriptor);
-    }
-    const grpcStreamMethods: string[] = [];
-    for (const method of grpcStreamMethods) {
-      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
-      GrpcStreamMethod("PaymentsService", method)(constructor.prototype[method], method, descriptor);
-    }
-  };
-}
-
-export const PAYMENTS_SERVICE_NAME = "PaymentsService";
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.10.1
+//   protoc               v7.35.0
+// source: payments.proto
+
+/* eslint-disable */
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { Observable } from "rxjs";
+
+export const protobufPackage = "payments.v1";
+
+export interface Ok {
+  ok: boolean;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * Purchase / checkout / topup
+ * ---------------------------------------------------------------------------
+ */
+export interface Purchase {
+  id: string;
+  productId: string;
+  productName: string;
+  userId: string;
+  /** settled RUB amount */
+  price: string;
+  /** PENDING | COMPLETED | FAILED | REFUNDED */
+  status: string;
+  paymentId: string;
+  /** BALANCE | YOOKASSA | CRYPTO */
+  paymentMethod: string;
+  commissionPercent: string;
+  sellerAmount: string;
+  createdAt: string;
+  completedAt: string;
+  /** FX snapshot at checkout (empty for legacy RUB purchases). */
+  listingCurrency: string;
+  /** Decimal as string, in listing_currency */
+  listingPrice: string;
+  /** listing→RUB rate used (Decimal as string) */
+  fxRate: string;
+}
+
+export interface TopupRequest {
+  userId: string;
+  /** >= 10.00 */
+  amount: string;
+  returnUrl: string;
+  /** YOOKASSA | SAVED_CARD | CRYPTO (default YOOKASSA) */
+  paymentMethod: string;
+  /** required when payment_method=SAVED_CARD */
+  savedCardId: string;
+}
+
+export interface CreateCheckoutRequest {
+  userId: string;
+  productId: string;
+  /** BALANCE | YOOKASSA | SAVED_CARD | CRYPTO (default YOOKASSA) */
+  paymentMethod: string;
+  returnUrl: string;
+  /**
+   * When payment_method=SAVED_CARD — required. ID of a SavedCard row owned
+   * by user_id. Ignored otherwise.
+   */
+  savedCardId: string;
+  /**
+   * When payment_method=YOOKASSA — optional. If true, save the card token
+   * after success; the bound card becomes available in /account/cards.
+   */
+  savePaymentMethod: boolean;
+}
+
+export interface BindCardRequest {
+  userId: string;
+  returnUrl: string;
+}
+
+export interface GetPaymentIntentRequest {
+  intentId: string;
+  /** ownership check */
+  userId: string;
+}
+
+export interface PaymentIntentStatus {
+  id: string;
+  userId: string;
+  /** TOPUP | PREMIUM */
+  purpose: string;
+  /** PENDING | COMPLETED | FAILED | CANCELED */
+  status: string;
+  amount: string;
+  currency: string;
+  /** set when purpose=PREMIUM (else empty) */
+  purchaseId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CheckoutResponse {
+  purchaseId: string;
+  paymentId: string;
+  /** empty when paid from balance (instant) */
+  confirmationUrl: string;
+  /** PENDING (redirect) | COMPLETED (balance) */
+  status: string;
+  /** poll via GetPaymentIntent for TOPUP / bind-card flows */
+  intentId: string;
+}
+
+export interface GetMyPurchasesRequest {
+  userId: string;
+  page: number;
+  limit: number;
+}
+
+export interface PurchasesListResponse {
+  items: Purchase[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface GetPurchaseRequest {
+  id: string;
+  userId: string;
+}
+
+export interface RefundPurchaseRequest {
+  purchaseId: string;
+  actorUserId: string;
+  isAdmin: boolean;
+  reason: string;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * Wallet & statement
+ * ---------------------------------------------------------------------------
+ */
+export interface GetWalletRequest {
+  userId: string;
+}
+
+export interface WalletResponse {
+  spending: string;
+  pending: string;
+  payout: string;
+  /** spending + payout */
+  spendable: string;
+  /** payout */
+  withdrawable: string;
+  currency: string;
+  lifetimeSales: number;
+  currentCommissionPercent: string;
+}
+
+export interface ListTransactionsRequest {
+  userId: string;
+  /**
+   * 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 {
+  id: string;
+  txId: string;
+  /** raw tx type (TOPUP|PURCHASE|...) */
+  type: string;
+  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 {
+  items: StatementEntry[];
+  total: number;
+  page: number;
+  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
+ * ---------------------------------------------------------------------------
+ */
+export interface Withdrawal {
+  id: string;
+  sellerId: string;
+  amount: string;
+  /** PENDING | PROCESSING | COMPLETED | REJECTED */
+  status: string;
+  method: string;
+  details: string;
+  comment: string;
+  processedBy: string;
+  processedAt: string;
+  createdAt: string;
+}
+
+export interface RequestWithdrawalRequest {
+  sellerId: string;
+  amount: string;
+  method: string;
+  details: string;
+}
+
+export interface ListWithdrawalsRequest {
+  sellerId: string;
+  status: string;
+  page: number;
+  limit: number;
+}
+
+export interface WithdrawalsListResponse {
+  items: Withdrawal[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface ProcessWithdrawalRequest {
+  withdrawalId: string;
+  adminId: string;
+  action: string;
+  comment: string;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * Webhook
+ * ---------------------------------------------------------------------------
+ */
+export interface PaymentEventRequest {
+  event: string;
+  paymentId: string;
+}
+
+export interface ProviderCallbackRequest {
+  /** yookassa | heleket | … */
+  provider: string;
+  /** exact raw JSON body as received (signature input) */
+  rawBody: string;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * FX rates / payment methods
+ * ---------------------------------------------------------------------------
+ */
+export interface GetRatesRequest {
+}
+
+export interface FxRate {
+  /** USD | EUR */
+  currency: string;
+  /** RUB per 1 unit, Decimal as string */
+  rate: string;
+}
+
+export interface GetRatesResponse {
+  /** always RUB */
+  base: string;
+  /** YYYY-MM-DD the rates are for */
+  asOf: string;
+  rates: FxRate[];
+}
+
+export interface GetPaymentMethodsRequest {
+}
+
+export interface PaymentMethodInfo {
+  /** YOOKASSA | SAVED_CARD | CRYPTO | BALANCE */
+  method: string;
+  /** yookassa | heleket | '' (BALANCE) */
+  provider: string;
+  currencies: string[];
+}
+
+export interface GetPaymentMethodsResponse {
+  methods: PaymentMethodInfo[];
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * 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;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * Premium
+ * ---------------------------------------------------------------------------
+ */
+export interface GetPremiumPlansRequest {
+}
+
+/**
+ * One plan per (period). Prices are computed server-side from BASE_PRICE × months
+ * × (1 − discount); kept here as canonical strings so the gateway has no math.
+ */
+export interface PremiumPlan {
+  /** MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12 */
+  period: string;
+  months: number;
+  /** total to charge, Decimal-as-string */
+  price: string;
+  /** for UI "≈ X ₽/month" */
+  monthlyPrice: string;
+  discountPercent: string;
+  currency: string;
+}
+
+export interface PremiumPlansResponse {
+  plans: PremiumPlan[];
+  baseMonthlyPrice: string;
+}
+
+export interface PurchasePremiumRequest {
+  userId: string;
+  /** MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12 */
+  period: string;
+  /** BALANCE | YOOKASSA | SAVED_CARD (empty = smart default) */
+  paymentMethod: string;
+  /** YooKassa only */
+  returnUrl: string;
+  /**
+   * Save the YooKassa payment_method for future auto-renewals. Ignored for
+   * BALANCE. Kept for backwards compatibility; auto_renew=true implies save.
+   */
+  savePaymentMethod: boolean;
+  /** default false; requires off-session-capable method */
+  autoRenew: boolean;
+  /** optional for SAVED_CARD; empty = default card */
+  savedCardId: string;
+}
+
+export interface PurchasePremiumResponse {
+  /** PremiumPayment.id */
+  paymentId: string;
+  /** empty for BALANCE (instant) or YooKassa-issued */
+  confirmationUrl: string;
+  /** PENDING (redirect) | COMPLETED (balance) */
+  status: string;
+}
+
+export interface RunPremiumRenewalsRequest {
+  /** safety cap; default 100 */
+  maxBatch: number;
+}
+
+export interface RunPremiumRenewalsResponse {
+  attempted: number;
+  succeeded: number;
+  failed: number;
+}
+
+export interface SetPremiumPaymentMethodRequest {
+  userId: string;
+  /** BALANCE | YOOKASSA | SAVED_CARD */
+  method: string;
+  /** optional for SAVED_CARD; empty = default card */
+  savedCardId: string;
+}
+
+export interface PremiumPaymentMethodResponse {
+  /** BALANCE | YOOKASSA | SAVED_CARD */
+  method: string;
+  /** empty unless SAVED_CARD */
+  savedCardId: string;
+  autoRenew: boolean;
+}
+
+export interface PremiumPaymentRow {
+  id: string;
+  userId: string;
+  amount: string;
+  /** MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12 */
+  period: string;
+  /** BALANCE | YOOKASSA */
+  method: string;
+  /** PENDING | COMPLETED | FAILED | REFUNDED */
+  status: string;
+  isRenewal: boolean;
+  createdAt: string;
+  completedAt: string;
+  refundedAt: string;
+  refundedAmount: string;
+  /**
+   * Convenience: true if this payment is currently inside the 7-day refund
+   * window AND status == COMPLETED AND not already refunded.
+   */
+  refundable: boolean;
+}
+
+export interface RefundPremiumRequest {
+  userId: string;
+  paymentId: string;
+  /** optional */
+  reason: string;
+}
+
+export interface RefundPremiumResponse {
+  payment:
+    | PremiumPaymentRow
+    | undefined;
+  /** ISO 8601 after rollback */
+  newExpiresAt: string;
+  /** true when rollback put expiresAt <= now */
+  subscriptionRevoked: boolean;
+}
+
+export interface GetMyPremiumPaymentsRequest {
+  userId: string;
+  page: number;
+  limit: number;
+}
+
+export interface GetPremiumPaymentRequest {
+  userId: string;
+  paymentId: string;
+}
+
+export interface PremiumPaymentsListResponse {
+  items: PremiumPaymentRow[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * Saved cards (YooKassa payment_method tokens; we never see PAN)
+ * ---------------------------------------------------------------------------
+ */
+export interface SavedCard {
+  id: string;
+  /** "MIR" | "VISA" | "MASTERCARD" | "" */
+  brand: string;
+  /** "0000" etc, display-only */
+  last4: string;
+  expMonth: number;
+  expYear: number;
+  isDefault: boolean;
+  /** user-set label */
+  nickname: string;
+  createdAt: string;
+}
+
+export interface ListSavedCardsRequest {
+  userId: string;
+}
+
+export interface ListSavedCardsResponse {
+  items: SavedCard[];
+}
+
+export interface DeleteSavedCardRequest {
+  userId: string;
+  id: string;
+}
+
+export interface SetDefaultSavedCardRequest {
+  userId: string;
+  id: string;
+}
+
+export interface UpdateSavedCardRequest {
+  userId: string;
+  id: string;
+  /** empty = clear */
+  nickname: string;
+}
+
+/**
+ * ---------------------------------------------------------------------------
+ * Payout details (persistent default; per-withdrawal override still allowed)
+ * ---------------------------------------------------------------------------
+ */
+export interface UpdatePayoutDetailsRequest {
+  userId: string;
+  /** "card" | "sbp" | "bank" | "" (clear) */
+  method: string;
+  /** JSON string — payments-service treats opaquely */
+  details: string;
+}
+
+export interface UpdatePayoutDetailsResponse {
+  method: string;
+  details: string;
+}
+
+export interface GetPayoutDetailsRequest {
+  userId: string;
+}
+
+export const PAYMENTS_V1_PACKAGE_NAME = "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).
+ */
+
+export interface PaymentsServiceClient {
+  /** ----- buyer ----- */
+
+  topup(request: TopupRequest): Observable<CheckoutResponse>;
+
+  createCheckout(request: CreateCheckoutRequest): Observable<CheckoutResponse>;
+
+  getMyPurchases(request: GetMyPurchasesRequest): Observable<PurchasesListResponse>;
+
+  getPurchase(request: GetPurchaseRequest): Observable<Purchase>;
+
+  refundPurchase(request: RefundPurchaseRequest): Observable<Purchase>;
+
+  /** ----- wallet ----- */
+
+  getWallet(request: GetWalletRequest): Observable<WalletResponse>;
+
+  listTransactions(request: ListTransactionsRequest): Observable<TransactionsListResponse>;
+
+  getTransactionMonths(request: GetTransactionMonthsRequest): Observable<GetTransactionMonthsResponse>;
+
+  /** ----- 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>;
+
+  /**
+   * Generalized per-provider callback (POST /payments/webhook/:provider).
+   * Carries the EXACT raw JSON body: signed providers (Heleket) hash the
+   * byte-exact payload, so re-serializing a parsed body would break the sign.
+   */
+
+  handleProviderCallback(request: ProviderCallbackRequest): Observable<Ok>;
+
+  /** ----- premium ----- */
+
+  getPremiumPlans(request: GetPremiumPlansRequest): Observable<PremiumPlansResponse>;
+
+  purchasePremium(request: PurchasePremiumRequest): Observable<PurchasePremiumResponse>;
+
+  setPremiumPaymentMethod(request: SetPremiumPaymentMethodRequest): Observable<PremiumPaymentMethodResponse>;
+
+  /**
+   * 7-day refund window from completedAt. Reverses ledger, calls YooKassa for
+   * card purchases, rolls back the subscription's expiresAt by the period.
+   */
+
+  refundPremium(request: RefundPremiumRequest): Observable<RefundPremiumResponse>;
+
+  getMyPremiumPayments(request: GetMyPremiumPaymentsRequest): Observable<PremiumPaymentsListResponse>;
+
+  getPremiumPayment(request: GetPremiumPaymentRequest): Observable<PremiumPaymentRow>;
+
+  /**
+   * Internal — InternalServiceGuard. tasks-service cron triggers due renewals;
+   * payments-service iterates ACTIVE subscriptions with autoRenew+savedCard.
+   */
+
+  runPremiumRenewals(request: RunPremiumRenewalsRequest): Observable<RunPremiumRenewalsResponse>;
+
+  /** ----- saved cards ----- */
+
+  listSavedCards(request: ListSavedCardsRequest): Observable<ListSavedCardsResponse>;
+
+  deleteSavedCard(request: DeleteSavedCardRequest): Observable<Ok>;
+
+  setDefaultSavedCard(request: SetDefaultSavedCardRequest): Observable<SavedCard>;
+
+  updateSavedCard(request: UpdateSavedCardRequest): Observable<SavedCard>;
+
+  /**
+   * Standalone "bind card" flow: creates a 1₽ YooKassa charge with
+   * save_payment_method=true; after the webhook the SavedCard row is
+   * persisted and the 1₽ credits USER_SPENDING so the user keeps it.
+   */
+
+  bindCard(request: BindCardRequest): Observable<CheckoutResponse>;
+
+  /**
+   * Poll an intent after returnUrl redirect: TOPUP/PREMIUM completion, bind-card
+   * completion. Ownership-checked by user_id.
+   */
+
+  getPaymentIntent(request: GetPaymentIntentRequest): Observable<PaymentIntentStatus>;
+
+  /**
+   * ----- FX / available methods (public, cached) -----
+   * Daily CBR rates (RUB base). Frontend uses this for the "≈" display hint;
+   * the authoritative charge amount is always computed server-side at checkout.
+   */
+
+  getRates(request: GetRatesRequest): Observable<GetRatesResponse>;
+
+  /**
+   * Payment methods derived from live provider capabilities — the client
+   * renders only what is actually available (e.g. CRYPTO appears once the
+   * Heleket merchant is configured).
+   */
+
+  getPaymentMethods(request: GetPaymentMethodsRequest): Observable<GetPaymentMethodsResponse>;
+
+  /** ----- payout details ----- */
+
+  updatePayoutDetails(request: UpdatePayoutDetailsRequest): Observable<UpdatePayoutDetailsResponse>;
+
+  getPayoutDetails(request: GetPayoutDetailsRequest): Observable<UpdatePayoutDetailsResponse>;
+
+  /** ----- 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 + 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;
+
+  getMyPurchases(
+    request: GetMyPurchasesRequest,
+  ): Promise<PurchasesListResponse> | Observable<PurchasesListResponse> | PurchasesListResponse;
+
+  getPurchase(request: GetPurchaseRequest): Promise<Purchase> | Observable<Purchase> | Purchase;
+
+  refundPurchase(request: RefundPurchaseRequest): Promise<Purchase> | Observable<Purchase> | Purchase;
+
+  /** ----- wallet ----- */
+
+  getWallet(request: GetWalletRequest): Promise<WalletResponse> | Observable<WalletResponse> | WalletResponse;
+
+  listTransactions(
+    request: ListTransactionsRequest,
+  ): Promise<TransactionsListResponse> | Observable<TransactionsListResponse> | TransactionsListResponse;
+
+  getTransactionMonths(
+    request: GetTransactionMonthsRequest,
+  ): Promise<GetTransactionMonthsResponse> | Observable<GetTransactionMonthsResponse> | GetTransactionMonthsResponse;
+
+  /** ----- withdrawals ----- */
+
+  requestWithdrawal(request: RequestWithdrawalRequest): Promise<Withdrawal> | Observable<Withdrawal> | Withdrawal;
+
+  listWithdrawals(
+    request: ListWithdrawalsRequest,
+  ): 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;
+
+  /**
+   * Generalized per-provider callback (POST /payments/webhook/:provider).
+   * Carries the EXACT raw JSON body: signed providers (Heleket) hash the
+   * byte-exact payload, so re-serializing a parsed body would break the sign.
+   */
+
+  handleProviderCallback(request: ProviderCallbackRequest): Promise<Ok> | Observable<Ok> | Ok;
+
+  /** ----- premium ----- */
+
+  getPremiumPlans(
+    request: GetPremiumPlansRequest,
+  ): Promise<PremiumPlansResponse> | Observable<PremiumPlansResponse> | PremiumPlansResponse;
+
+  purchasePremium(
+    request: PurchasePremiumRequest,
+  ): Promise<PurchasePremiumResponse> | Observable<PurchasePremiumResponse> | PurchasePremiumResponse;
+
+  setPremiumPaymentMethod(
+    request: SetPremiumPaymentMethodRequest,
+  ): Promise<PremiumPaymentMethodResponse> | Observable<PremiumPaymentMethodResponse> | PremiumPaymentMethodResponse;
+
+  /**
+   * 7-day refund window from completedAt. Reverses ledger, calls YooKassa for
+   * card purchases, rolls back the subscription's expiresAt by the period.
+   */
+
+  refundPremium(
+    request: RefundPremiumRequest,
+  ): Promise<RefundPremiumResponse> | Observable<RefundPremiumResponse> | RefundPremiumResponse;
+
+  getMyPremiumPayments(
+    request: GetMyPremiumPaymentsRequest,
+  ): Promise<PremiumPaymentsListResponse> | Observable<PremiumPaymentsListResponse> | PremiumPaymentsListResponse;
+
+  getPremiumPayment(
+    request: GetPremiumPaymentRequest,
+  ): Promise<PremiumPaymentRow> | Observable<PremiumPaymentRow> | PremiumPaymentRow;
+
+  /**
+   * Internal — InternalServiceGuard. tasks-service cron triggers due renewals;
+   * payments-service iterates ACTIVE subscriptions with autoRenew+savedCard.
+   */
+
+  runPremiumRenewals(
+    request: RunPremiumRenewalsRequest,
+  ): Promise<RunPremiumRenewalsResponse> | Observable<RunPremiumRenewalsResponse> | RunPremiumRenewalsResponse;
+
+  /** ----- saved cards ----- */
+
+  listSavedCards(
+    request: ListSavedCardsRequest,
+  ): Promise<ListSavedCardsResponse> | Observable<ListSavedCardsResponse> | ListSavedCardsResponse;
+
+  deleteSavedCard(request: DeleteSavedCardRequest): Promise<Ok> | Observable<Ok> | Ok;
+
+  setDefaultSavedCard(request: SetDefaultSavedCardRequest): Promise<SavedCard> | Observable<SavedCard> | SavedCard;
+
+  updateSavedCard(request: UpdateSavedCardRequest): Promise<SavedCard> | Observable<SavedCard> | SavedCard;
+
+  /**
+   * Standalone "bind card" flow: creates a 1₽ YooKassa charge with
+   * save_payment_method=true; after the webhook the SavedCard row is
+   * persisted and the 1₽ credits USER_SPENDING so the user keeps it.
+   */
+
+  bindCard(request: BindCardRequest): Promise<CheckoutResponse> | Observable<CheckoutResponse> | CheckoutResponse;
+
+  /**
+   * Poll an intent after returnUrl redirect: TOPUP/PREMIUM completion, bind-card
+   * completion. Ownership-checked by user_id.
+   */
+
+  getPaymentIntent(
+    request: GetPaymentIntentRequest,
+  ): Promise<PaymentIntentStatus> | Observable<PaymentIntentStatus> | PaymentIntentStatus;
+
+  /**
+   * ----- FX / available methods (public, cached) -----
+   * Daily CBR rates (RUB base). Frontend uses this for the "≈" display hint;
+   * the authoritative charge amount is always computed server-side at checkout.
+   */
+
+  getRates(request: GetRatesRequest): Promise<GetRatesResponse> | Observable<GetRatesResponse> | GetRatesResponse;
+
+  /**
+   * Payment methods derived from live provider capabilities — the client
+   * renders only what is actually available (e.g. CRYPTO appears once the
+   * Heleket merchant is configured).
+   */
+
+  getPaymentMethods(
+    request: GetPaymentMethodsRequest,
+  ): Promise<GetPaymentMethodsResponse> | Observable<GetPaymentMethodsResponse> | GetPaymentMethodsResponse;
+
+  /** ----- payout details ----- */
+
+  updatePayoutDetails(
+    request: UpdatePayoutDetailsRequest,
+  ): Promise<UpdatePayoutDetailsResponse> | Observable<UpdatePayoutDetailsResponse> | UpdatePayoutDetailsResponse;
+
+  getPayoutDetails(
+    request: GetPayoutDetailsRequest,
+  ): Promise<UpdatePayoutDetailsResponse> | Observable<UpdatePayoutDetailsResponse> | UpdatePayoutDetailsResponse;
+
+  /** ----- 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",
+      "getMyPurchases",
+      "getPurchase",
+      "refundPurchase",
+      "getWallet",
+      "listTransactions",
+      "getTransactionMonths",
+      "requestWithdrawal",
+      "listWithdrawals",
+      "processWithdrawal",
+      "handlePaymentEvent",
+      "handleProviderCallback",
+      "getPremiumPlans",
+      "purchasePremium",
+      "setPremiumPaymentMethod",
+      "refundPremium",
+      "getMyPremiumPayments",
+      "getPremiumPayment",
+      "runPremiumRenewals",
+      "listSavedCards",
+      "deleteSavedCard",
+      "setDefaultSavedCard",
+      "updateSavedCard",
+      "bindCard",
+      "getPaymentIntent",
+      "getRates",
+      "getPaymentMethods",
+      "updatePayoutDetails",
+      "getPayoutDetails",
+      "getAdminOverview",
+      "adminListTransactions",
+      "getUserFinance",
+      "createAdjustment",
+      "getSalesAnalytics",
+    ];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("PaymentsService", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("PaymentsService", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const PAYMENTS_SERVICE_NAME = "PaymentsService";