feat: sync implement Stars friend gift packages

internal/domain/media.go

@@ -570,6 +570,9 @@ const (
 	// MessageServiceActionStarGift 映射 messageActionStarGift：收到一份 Star 礼物。
 	// 礼物快照（贴纸/星价）内嵌在 action 里，收礼人无需额外拉取即可渲染气泡。
 	MessageServiceActionStarGift MessageServiceActionKind = "star_gift"
+	// MessageServiceActionGiftStars maps messageActionGiftStars: fiat-purchased
+	// Stars credited directly to a friend, distinct from collectible Star Gifts.
+	MessageServiceActionGiftStars MessageServiceActionKind = "gift_stars"
 	// MessageServiceActionStarGiftUnique maps messageActionStarGiftUnique. The
 	// immutable collectible snapshot is carried by the service message so an
 	// exact replay/difference never depends on mutable catalog state.
@@ -659,11 +662,24 @@ type MessageServiceAction struct {
 	ChatThemeEmoticon     string                              `json:"chat_theme_emoticon,omitempty"`
 	NoForwards            *MessageNoForwardsAction            `json:"no_forwards,omitempty"`
 	StarGift              *MessageStarGiftAction              `json:"star_gift,omitempty"`
+	GiftStars             *MessageGiftStarsAction             `json:"gift_stars,omitempty"`
 	StarGiftUnique        *MessageStarGiftUniqueAction        `json:"star_gift_unique,omitempty"`
 	StarGiftOffer         *MessageStarGiftOfferAction         `json:"star_gift_offer,omitempty"`
 	StarGiftOfferDeclined *MessageStarGiftOfferDeclinedAction `json:"star_gift_offer_declined,omitempty"`
 }
 
+// MessageGiftStarsAction is the immutable service-message projection. The
+// recipient-only BalanceAfter field is not encoded in messageActionGiftStars;
+// it lets online push and offline difference attach the matching non-PTS
+// updateStarsBalance without querying mutable current state.
+type MessageGiftStarsAction struct {
+	Currency      string `json:"currency"`
+	Amount        int64  `json:"amount"`
+	Stars         int64  `json:"stars"`
+	TransactionID string `json:"transaction_id,omitempty"`
+	BalanceAfter  int64  `json:"balance_after"`
+}
+
 // MessageStarGiftAction 是 messageActionStarGift 的协议中立载荷：内嵌礼物快照（贴纸/星价）
 // 使收礼人无需额外拉取即可渲染。PeerUserID/PeerChannelID 为收礼方；NameHidden 时下发不暴露 from。
 type MessageStarGiftAction struct {

internal/domain/stars.go

@@ -17,6 +17,38 @@ type StarsBalance struct {
 	Granted bool  // 起始授予是否已应用（惰性首读授予的幂等守卫）
 }
 
+// StarsGiftPurchaseForm binds one short-lived fiat Stars-gift checkout to its
+// authenticated buyer, recipient and exact server-advertised package. The
+// client may echo these values but cannot use a form for a different intent.
+type StarsGiftPurchaseForm struct {
+	FormID          int64
+	BuyerUserID     int64
+	RecipientUserID int64
+	Stars           int64
+	Currency        string
+	Amount          int64
+	IssuedAt        int
+	ExpiresAt       int
+}
+
+// StarsGiftPurchaseRequest is the immutable settlement command carried by
+// inputInvoiceStars(inputStorePaymentStarsGift).
+type StarsGiftPurchaseRequest struct {
+	StarsGiftPurchaseForm
+	Date            int
+	OriginAuthKeyID [8]byte
+	OriginSessionID int64
+}
+
+// StarsGiftPurchaseResult is the atomically committed recipient credit and
+// bilateral service-message receipt. Duplicate means an exact form replay.
+type StarsGiftPurchaseResult struct {
+	RecipientBalance StarsBalance
+	Send             SendPrivateTextResult
+	TransactionID    string
+	Duplicate        bool
+}
+
 // StarsTransactionReason 标记一条流水的语义（投影到 tg.StarsTransaction 的标志位/标题）。
 type StarsTransactionReason string
 
@@ -152,6 +184,12 @@ var (
 	ErrStarsInvalidAmount = errors.New("stars: invalid amount")
 	// ErrStarsTransactionQueryInvalid 表示内部构造了不可能的流水方向。
 	ErrStarsTransactionQueryInvalid = errors.New("stars: invalid transaction query")
+	// ErrStarsGiftFormInvalid covers a missing/cross-account/mutated form.
+	ErrStarsGiftFormInvalid = errors.New("stars: gift form invalid")
+	// ErrStarsGiftFormExpired is returned before any settlement write.
+	ErrStarsGiftFormExpired = errors.New("stars: gift form expired")
+	// ErrStarsGiftUnavailable covers a recipient that cannot receive the gift.
+	ErrStarsGiftUnavailable = errors.New("stars: gift unavailable")
 )
 
 // StarsPaymentRequiredError reports the minimum paid-message authorization the