Gifts — Technical Reference

← Back to Gifts

Where this lives

Backend

• apps/backend/graphql/types/gift.type.js — GiftCatalogItem, Gift, GiftTargetStats, SendGiftInput, SendGiftResponse; queries giftCatalog / giftStatsForTarget / giftsForTarget; mutation sendGift.
• apps/backend/graphql/resolvers/gift.resolver.js — wires the above to the manager.
• apps/backend/managers/coin-managers/gift.manager.js — catalog, balance check, coin transfer, stats.
• apps/backend/database/models/Gift.js + migration 20260721000000-create-gift.js — the gift table.
• apps/backend/data-access-services/gift/gift.access-service.js — Gift row persistence + the GROUP BY gift_type aggregation behind getStatsForTarget.
• apps/backend/graphql/types/post.type.js / post.resolver.js — Post.giftStats: GiftTargetStats! is resolved per-post via gift.manager#getStatsForTarget, so the feed query gets gift totals bundled onto each post instead of a separate giftStatsForTarget round-trip per card.

Live gifts are a separate system (live-stream-gift.type.js / live-stream-gift.resolver.js / LiveStreamGift.js, mutation sendLiveGift); don't confuse the two.

Frontend

• apps/frontend-nextjs/src/components/gifts/GiftPicker.tsx — the sticker picker (loads giftCatalog, calls sendGift).
• apps/frontend-nextjs/src/components/gifts/GiftsModal.tsx — per-target received-gifts view (giftStatsForTarget / giftsForTarget).
• Entry points: components/chat/ChatView.tsx (1:1 chat header gift button), components/PostCard.tsx, components/stories/StoryViewer.tsx, and page-components/LiveRoomPage.tsx (live variant).

GraphQL

type GiftCatalogItem { giftType: String!  label: String!  emoji: String!  coinAmount: Int! }

input SendGiftInput {
  "One of: post, story, clip, user."
  targetType: String!
  targetId: ID!
  giftType: String!
  message: String
}

type SendGiftResponse {
  success: Boolean!
  message: String        # error detail when success is false (e.g. insufficient balance)
  giftType: String
  emoji: String
  coinAmount: Int
  newBalance: Int        # sender's coin balance after the gift
}

extend type Query {
  giftCatalog: [GiftCatalogItem!]!
  giftStatsForTarget(targetType: String!, targetId: ID!): GiftTargetStats!
  giftsForTarget(targetType: String!, targetId: ID!, limit: Int, offset: Int): [Gift!]!
}
extend type Mutation {
  sendGift(input: SendGiftInput!): SendGiftResponse!
}

GiftTargetStats breaks down accumulated gifts on a target as byType: [GiftTargetStatItem!] (per sticker: count, totalCoins) plus totalCoins / totalGifts.

Notes

• Pricing is the catalog coinAmount; the manager verifies the sender's balance before transferring, so sendGift returns success:false with a message rather than throwing on insufficient funds.
• sendGift also creates a gift-type notification for the recipient and returns the sender's post-gift balance (newBalance, via coinTransactionManager#getUserBalance); both are best-effort and never fail the gift itself.
• myGiftablePosts is not part of this system despite the name — it lives in top-fans.type.js / top-fans.resolver.js / top-fans.manager.js and lists a creator's paid posts offered as a rewardTopFan reward (premium_post), used only by RewardFanModal.tsx. See the Top Fans reference.