Skip to main content

Generated from package comments and exported declarations. Edit the Go source, not this file.

rewards

import "codeberg.org/hemanta212/playgo/api/rewards"

Package rewards defines reward balances, events, missions, marketplace, roulette, and sandbox contracts.

Rewards are XP, diamonds, spin tokens, and freeplay. They are tracked separately from cash and are not interchangeable with it, even where freeplay carries value and is represented in cents.

Admin operations use these types for manual grants, history reads, and local sandbox sessions. Reward changes are event-backed and idempotent where they mutate balances, so an operator grant is auditable next to everything the player earned normally.

The sandbox is local and dev only, runs in memory, and never touches production state. It exists for walking through reward scenarios deterministically.

Variables​

var (
// ErrMissionNotQualified rejects a claim whose completion requirement is not met.
ErrMissionNotQualified = errors.New("rewards: mission not qualified")
// ErrMissionExpired rejects a claim whose grace window has passed.
// Already-claimed periods are not errors: the stored result is replayed.
ErrMissionExpired = errors.New("rewards: mission expired")
// ErrDailyFreeplayCeilingReached refuses a mission claim while the
// player's daily freeplay ceiling is used up (ADR 0023); the mission stays
// claimable inside its grace window.
ErrDailyFreeplayCeilingReached = errors.New("rewards: daily free play ceiling reached")
)
var (
ErrSignupRuleConflict = errors.New("signup rule version or command conflict")
ErrSignupRuleCommandNotFound = errors.New("signup rule command not found")
)
var (
ErrInvalidRequest = errors.New("rewards: invalid request")
ErrNotFound = errors.New("rewards: not found")
ErrInsufficientBalance = errors.New("rewards: insufficient balance")
ErrInsufficientXP = errors.New("rewards: insufficient xp")
ErrNoSpinTokens = errors.New("rewards: no spin tokens")
ErrConflict = errors.New("rewards: idempotency conflict")
// ErrBonusAlreadyPending rejects a next_deposit_100_max_10 claim while a
// Pending Next-Deposit Bonus already exists (specs/simple-rewards-v1
// "Re-claim rejected while deposit bonus pending").
ErrBonusAlreadyPending = errors.New("rewards: deposit bonus already pending")
ErrUnsafeDepositReversal = errors.New("rewards: deposit reward reversal is not safe")
)

AdminGrantReasons is why an admin gives a player a reward: each code and the phrase its audit text starts with.

var AdminGrantReasons = reasoncode.Vocabulary{
"goodwill": "Goodwill",
"compensation": "Compensation for a problem",
"promotion": "Promotion",
"missed_reward": "Missed reward",
"test_credit": "Test credit",
"other": "Other",
}

type AdminGrantCommand​

type AdminGrantCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
Kind BalanceKind
Amount int64
// ReasonCode comes from AdminGrantReasons; Note is optional except for
// other. The service composes the audit text from both.
ReasonCode string
Note string
IdempotencyKey string
}

type Balance​

type Balance struct {
UserID uuid.UUID
XP int64
LifetimeXP int64
Diamonds int64
SpinTokens int64
DepositBonusCents int64
FreeplayCents int64
PendingNextDepositBonusPct int32
PendingNextDepositBonusLimit int64
UpdatedAt time.Time
}

type BalanceDelta​

type BalanceDelta struct {
XP int64 `json:"xp"`
Diamonds int64 `json:"diamonds"`
SpinTokens int64 `json:"spin_tokens"`
DepositBonusCents int64 `json:"deposit_bonus_cents"`
FreeplayCents int64 `json:"freeplay_cents"`
PendingNextDepositBonusPct int32 `json:"pending_next_deposit_bonus_pct"`
PendingNextDepositBonusLimit int64 `json:"pending_next_deposit_bonus_limit_cents"`
ClearPendingNextDepositBonus bool `json:"clear_pending_next_deposit_bonus"`
ResetXP bool `json:"reset_xp"`
}

type BalanceKind​

type BalanceKind string
const (
BalanceKindXP BalanceKind = "xp"
BalanceKindDiamonds BalanceKind = "diamonds"
BalanceKindSpinTokens BalanceKind = "spin_tokens"
BalanceKindFreeplayCents BalanceKind = "freeplay_cents"
)

type Calculation​

Calculation is how a deposit reward or a mission claim worked out its amount, as recorded in the reward event's metadata when it was granted (Olin 120921: staff must see which rule paid, its inputs, the caps and the result). Every amount is one Postgres computed during the grant; readers display them and never recompute. A key is absent when the step did not apply, and events granted before a key existed simply lack it.

type Calculation struct {
MissionID MissionID `json:"mission_id,omitempty"`
RulesVersion int64 `json:"bonus_settings_version,omitempty"`
// SchemeID is the bonus scheme whose rule paid a mission claim; nil = base rules.
SchemeID *uuid.UUID `json:"bonus_scheme_id,omitempty"`
// DepositCents is the settled deposit a deposit reward was computed from.
DepositCents int64 `json:"amount_cents,omitempty"`

Mission *MissionCalculation `json:"calculation,omitempty"`
NextDepositBonus *NextDepositBonusCalculation `json:"next_deposit_bonus,omitempty"`
Campaign *CampaignCalculation `json:"campaign,omitempty"`
EveryDeposit *EveryDepositCalculation `json:"every_deposit,omitempty"`

// A first- or second-deposit match claim pays only what exceeds that deposit's every-deposit bonus.
EveryDepositBonusCents *int64 `json:"every_deposit_bonus_cents,omitempty"`
ReducedByEveryDepositFromCents *int64 `json:"reduced_by_every_deposit_from_cents,omitempty"`
// The daily freeplay ceiling cut the claim from CeilingReducedFromCents to what was left of DailyCeilingCents.
CeilingReducedFromCents *int64 `json:"ceiling_reduced_from_cents,omitempty"`
DailyCeilingCents *int64 `json:"daily_ceiling_cents,omitempty"`
}

type CampaignCalculation​

CampaignCalculation is the claimed deposit campaign that paid the deposit (the best one when several applied).

type CampaignCalculation struct {
CampaignID uuid.UUID `json:"campaign_id"`
Title string `json:"title"`
Percent int32 `json:"percent"`
CapLeftCents int64 `json:"cap_left_cents"`
BonusCents int64 `json:"bonus_cents"`
}

type CommandResult​

type CommandResult struct {
Balance Balance
Event Event
Replayed bool
}

type DepositRewardReversalPreview​

type DepositRewardReversalPreview struct {
PaymentID uuid.UUID
UserID uuid.UUID
OriginalEventID uuid.UUID
XP int64
Diamonds int64
SpinTokens int64
FreeplayCents int64
PendingBonusConsumed bool
LaterRewardEventID *uuid.UUID
BalancesSufficient bool
AlreadyReversed bool
}

type Event​

type Event struct {
ID uuid.UUID
UserID uuid.UUID
ActorID uuid.UUID
Kind EventKind
Delta BalanceDelta
Balance Balance
Reason string
Metadata map[string]any
CreatedAt time.Time
}

type EventKind​

type EventKind string
const (
EventKindInappSignupFreeplay EventKind = "inapp_signup_freeplay"
EventKindDepositReward EventKind = "deposit_reward"
EventKindDepositReversal EventKind = "deposit_reversal"
EventKindDailyLoginXP EventKind = "daily_login_xp"
EventKindWeeklyLoginXP EventKind = "weekly_login_xp"
EventKindXPRewardClaim EventKind = "xp_reward_claim"
EventKindMarketplacePurchase EventKind = "marketplace_purchase"
EventKindRouletteSpin EventKind = "roulette_spin"
EventKindAdminGrant EventKind = "admin_grant"
EventKindCampaignClaim EventKind = "campaign_claim"
EventKindAdminClawback EventKind = "admin_clawback"
EventKindMissionClaim EventKind = "mission_claim"
EventKindReferralReferrerReward EventKind = "referral_referrer_reward"
EventKindReferralRefereeBonus EventKind = "referral_referee_bonus"
EventKindReferralMilestoneClaim EventKind = "referral_milestone_claim"
)

type EveryDepositCalculation​

EveryDepositCalculation is the every-deposit bonus of a deposit. It never stacks with the deposit's other bonuses (OtherBonusCents): the deposit pays the larger, so PaidCents is what exceeded them.

type EveryDepositCalculation struct {
PercentBps int32 `json:"percent_bps"`
CapCents int64 `json:"cap_cents"`
BonusCents int64 `json:"bonus_cents"`
OtherBonusCents *int64 `json:"other_bonus_cents,omitempty"`
PaidCents int64 `json:"paid_cents"`
RulesVersion int64 `json:"bonus_settings_version"`
SchemeID *uuid.UUID `json:"scheme_id,omitempty"`
}

type History​

type History struct {
Events []Event
}

type LoginClaimCommand​

type LoginClaimCommand struct {
UserID uuid.UUID
Date time.Time
}

type MarketplaceProduct​

type MarketplaceProduct struct {
ID string
Kind ProductKind
DiamondCost int64
XPGrant int64
SpinTokenGrant int64
FreeplayCents int64
}

type MarketplacePurchaseCommand​

type MarketplacePurchaseCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
ProductID string
IdempotencyKey string
}

type MissionCalculation​

MissionCalculation is a mission claim's payout before the every-deposit and daily-ceiling reductions: the payout basis, the measured input (an amount or a count), the rule's requirement, percent and cap, and the amount the rule computed.

type MissionCalculation struct {
Basis MissionPayoutBasis `json:"basis"`
// BaseCents is the deposit amount, deposit sum or deposit volume the mission measured.
BaseCents int64 `json:"base_cents,omitempty"`
// Count is the qualifying deposits or days the mission counted.
Count int64 `json:"count,omitempty"`
RequiredCents int64 `json:"required_cents,omitempty"`
RequiredCount int64 `json:"required_count,omitempty"`
Percent int32 `json:"percent,omitempty"`
CapCents int64 `json:"cap_cents,omitempty"`
// ComputedCents is the freeplay the rule computed (fixed or percent-and-cap); for the next-deposit tiers it is 0
// and Percent/CapCents are the pending bonus the claim set.
ComputedCents int64 `json:"computed_cents"`
}

type MissionCatalogEntry​

MissionCatalogEntry is one fixed v1 mission definition.

type MissionCatalogEntry struct {
ID MissionID
PeriodKind MissionPeriodKind
Payout MissionPayout
// DepositActivatedFreeplayCents is the extra freeplay the daily login claim
// grants once the account is Deposit-Activated (first successful deposit of
// any amount, permanent). Zero for other missions.
DepositActivatedFreeplayCents int64
// DepositActivatedSpinTokens is the Free Daily Spin count the daily login
// claim grants once the account is Deposit-Activated. Zero for other missions.
DepositActivatedSpinTokens int64
// Completion requirements (zero when not applicable).
RequiredQualifyingDeposits int64 // qualifying deposits in the period
RequiredQualifyingDays int64 // distinct qualifying-deposit days in the period
RequiredStreakDays int64 // consecutive qualifying-deposit days per Streak Run
RequiredVolumeCents int64 // total successful deposit volume in the period
RequiredReferralCount int64 // rewarded referrals required (lifetime milestone missions)
// NextLoadTiers are weekly_next_load's tiers, lowest first.
NextLoadTiers []MissionNextLoadTier
}

type MissionClaimCommand​

MissionClaimCommand is an explicit, idempotent mission claim. Identity is user + mission + period key — no client idempotency key is needed.

type MissionClaimCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
MissionID MissionID
// PeriodKey selects the period being claimed. Empty claims the period the
// service's clock resolves as currently claimable.
PeriodKey string
}

type MissionClaimResult​

MissionClaimResult is the stored, replayable result of a mission claim.

type MissionClaimResult struct {
MissionID MissionID
PeriodKey string
CommandResult
}

type MissionClaimability​

MissionClaimability is the state of one mission period for one user.

type MissionClaimability string
const (
MissionInProgress MissionClaimability = "in_progress"
MissionClaimable MissionClaimability = "claimable"
MissionClaimed MissionClaimability = "claimed"
MissionExpired MissionClaimability = "expired"
)

type MissionID​

MissionID is a typed v1 mission identifier. The catalog is fixed: no referral, jackpot, draw, or live-event missions.

type MissionID string
const (
MissionDailyLogin MissionID = "daily_login"
MissionDailyDepositMatch MissionID = "daily_deposit_match"
MissionDailyConsistentDeposit MissionID = "daily_consistent_deposit"
MissionDepositStreak3 MissionID = "deposit_streak_3"
MissionWeeklyConsistentDeposit MissionID = "weekly_consistent_deposit"
MissionWeeklyHighRoller MissionID = "weekly_high_roller"
MissionMonthlyDepositMilestone MissionID = "monthly_deposit_milestone"
// Missions added with the bonus rules (ADR 0023).
MissionSecondDepositMatch MissionID = "second_deposit_match"
MissionWeeklyNextLoad MissionID = "weekly_next_load"
MissionLoginStreak MissionID = "login_streak"
)

Referral-milestone missions (referrals-v2). These are lifetime missions whose progress is the count of the user's rewarded referrals — distinct from the fixed seven period-scoped missions above. They never expire and pay fixed XP + freeplay (no SQL money math). Catalog order matches MilestoneMissionIDs.

const (
MissionRefer5 MissionID = "refer_5"
MissionRefer10 MissionID = "refer_10"
MissionRefer20 MissionID = "refer_20"
)

func MilestoneMissionIDs​

func MilestoneMissionIDs() []MissionID

MilestoneMissionIDs lists the referral-milestone missions in catalog order.

func MissionIDs​

func MissionIDs() []MissionID

MissionIDs lists the period-scoped missions in catalog order. The referral-milestone missions are tracked separately (MilestoneMissionIDs).

func (MissionID) RewardKind​

func (id MissionID) RewardKind() MissionRewardKind

RewardKind is shared by catalog presentation and claim settlement.

type MissionNextLoadTier​

MissionNextLoadTier is one weekly_next_load tier: a week with at least RequiredVolumeCents of deposits earns Percent of the next deposit, at most CapCents, as freeplay.

type MissionNextLoadTier struct {
RequiredVolumeCents int64
Percent int32
CapCents int64
}

type MissionPayout​

MissionPayout describes a mission's reward. Only existing reward currencies — never withdrawable wallet cash (ADR 0002).

type MissionPayout struct {
Basis MissionPayoutBasis
// XP, FreeplayCents and DepositBonusCents are fixed amounts (basis "fixed").
XP int64
FreeplayCents int64
DepositBonusCents int64
// Percent and PercentCapCents instruct the claim transaction's SQL payout
// computation (percent bases only).
Percent int32
PercentCapCents int64
}

type MissionPayoutBasis​

MissionPayoutBasis says how a mission's freeplay payout amount is determined. Percent-based amounts are computed by SQL over numeric deposit amounts inside the claim transaction (LEAST with the cap), never in Go; fixed amounts come from config constants.

type MissionPayoutBasis string
const (
MissionPayoutFixed MissionPayoutBasis = "fixed"
// MissionPayoutPercentFirstQualifyingDeposit pays Percent of the period's
// first qualifying deposit, capped at PercentCapCents (daily_deposit_match).
MissionPayoutPercentFirstQualifyingDeposit MissionPayoutBasis = "percent_first_qualifying_deposit"
// MissionPayoutPercentQualifyingDepositSum pays Percent of the period's
// qualifying-deposit sum, capped at PercentCapCents (daily_consistent_deposit).
MissionPayoutPercentQualifyingDepositSum MissionPayoutBasis = "percent_qualifying_deposit_sum"
// MissionPayoutPercentSecondQualifyingDeposit pays Percent of the period's
// second qualifying deposit, capped at PercentCapCents (second_deposit_match).
MissionPayoutPercentSecondQualifyingDeposit MissionPayoutBasis = "percent_second_qualifying_deposit"
// MissionPayoutNextDepositBonusTiers sets a pending next-deposit bonus from
// the highest NextLoadTiers tier the week's deposits reached (weekly_next_load).
MissionPayoutNextDepositBonusTiers MissionPayoutBasis = "next_deposit_bonus_tiers"
)

type MissionPeriodKind​

MissionPeriodKind is the Reward Period shape a mission lives in.

type MissionPeriodKind string
const (
MissionPeriodDay MissionPeriodKind = "day"
MissionPeriodWeek MissionPeriodKind = "week"
MissionPeriodMonth MissionPeriodKind = "month"
MissionPeriodStreakRun MissionPeriodKind = "streak_run"
// MissionPeriodLifetime is the referral-milestone period: a single lifetime
// run keyed by the milestone (refer_5/10/20) that never expires.
MissionPeriodLifetime MissionPeriodKind = "lifetime"
)

type MissionProgress​

MissionProgress is the derived state of one mission period for one user.

type MissionProgress struct {
MissionID MissionID
PeriodKind MissionPeriodKind
// PeriodKey is the claim identity key: day "2006-01-02", week Monday date
// "2006-01-02", month "2006-01", streak-run start day "2006-01-02".
PeriodKey string
PeriodStart time.Time
PeriodEnd time.Time
ClaimableUntil time.Time // PeriodEnd + grace window (NY calendar days)
DailyLimitResetsAt *time.Time // Set when the daily ceiling blocks this claim.
State MissionClaimability
Completed bool
// Progress counters (zero when not applicable to the mission).
QualifyingDeposits int64
QualifyingDays int64
StreakProgressDays int64
VolumeCents int64
QualifyingDepositSumCents int64
FirstQualifyingDepositCents int64
DepositActivated bool // daily_login only
ReferralCount int64 // rewarded referrals so far (lifetime milestone missions)
ClaimedPayout *MissionPayout // persisted payout for claimed referral milestones
// EveryDepositBonusCents is what the every-deposit rule computed for the deposit this match mission pays on
// (first- and second-deposit match only); PayoutAfterEveryDepositCents is what the claim will then pay: the
// match minus that bonus, never below zero. Both are zero when no every-deposit bonus applies.
EveryDepositBonusCents int64
PayoutAfterEveryDepositCents int64
}

type MissionRewardKind​

MissionRewardKind names the asset paid by a mission, including a pending deposit bonus.

type MissionRewardKind string
const (
MissionRewardReferralBonus MissionRewardKind = "referral_bonus"
MissionRewardFreeplay MissionRewardKind = "freeplay"
MissionRewardDepositBonus MissionRewardKind = "deposit_bonus"
)

type MissionsSummary​

MissionsSummary is the missions read model: the fixed v1 catalog plus the derived progress entries the user can act on — every mission's current period, completed previous periods still inside the grace window, and one entry per derived Streak Run (plus the live partial run). Progress is derived on read; only claims persist (ADR 0003). WeeklyLoginStreaks carries the non-catalog weekly login streak: the current week always, plus the previous week while it is completed or claimed (a completed previous week stays claimable through the grace window, mirroring ClaimWeeklyLogin's candidates). Both can be relevant at once — previous week claimable in grace while the current week is in progress — hence a slice.

type MissionsSummary struct {
Catalog []MissionCatalogEntry
Entries []MissionProgress
WeeklyLoginStreaks []WeeklyLoginStreak
}

type NextDepositBonusCalculation​

NextDepositBonusCalculation is the pending next-deposit bonus a qualifying deposit consumed.

type NextDepositBonusCalculation struct {
Percent int32 `json:"percent"`
LimitCents int64 `json:"limit_cents"`
BonusCents int64 `json:"bonus_cents"`
}

type ProductKind​

type ProductKind string
const (
ProductKindLevelUp ProductKind = "level_up"
ProductKindWheelSpins ProductKind = "wheel_spins"
ProductKindFreeplay ProductKind = "freeplay"
)

type ReferralBonusGrantCommand​

type ReferralBonusGrantCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
PaymentID uuid.UUID
Kind EventKind
AmountCents int64
Metadata map[string]any
}

type ReferralFreeplayGrantCommand​

type ReferralFreeplayGrantCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
Kind EventKind
AmountCents int64
Metadata map[string]any
}

type ReverseDepositRewardCommand​

type ReverseDepositRewardCommand struct {
PaymentID uuid.UUID
ActorID uuid.UUID
UserID uuid.UUID
Reason string
}

type RewardChoice​

type RewardChoice struct {
ID string
Kind RewardChoiceKind
RequiredXP int64
FreeplayCents int64
NextDepositBonusPercent int32
NextDepositBonusCapCents int64
}

type RewardChoiceKind​

type RewardChoiceKind string
const (
RewardChoiceKindFreeplay RewardChoiceKind = "freeplay"
RewardChoiceKindNextDepositBonus RewardChoiceKind = "next_deposit_bonus"
)

type RouletteOutcome​

type RouletteOutcome struct {
ID string
Kind RouletteOutcomeKind
Weight int64 `json:"-"`
XPGrant int64
DiamondGrant int64
SpinTokenGrant int64
}

type RouletteOutcomeKind​

type RouletteOutcomeKind string
const (
RouletteOutcomeKindNoPrize RouletteOutcomeKind = "no_prize"
RouletteOutcomeKindDiamonds RouletteOutcomeKind = "diamonds"
RouletteOutcomeKindXP RouletteOutcomeKind = "xp"
RouletteOutcomeKindExtraSpin RouletteOutcomeKind = "extra_spin"
)

type RouletteSpinCommand​

type RouletteSpinCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
IdempotencyKey string
Roll int64
}

type SandboxArmedError​

SandboxArmedError is an operator-armed failure mode applied to the next matching simulated command, then cleared (fire-once).

type SandboxArmedError string
const (
// SandboxArmClaimRejection fails the next claim command (daily login, weekly
// streak, mission, XP reward) with the production rejection error.
SandboxArmClaimRejection SandboxArmedError = "claim_rejection"
// SandboxArmInsufficientBalance fails the next spend command (marketplace,
// roulette, XP reward) with ErrInsufficientBalance.
SandboxArmInsufficientBalance SandboxArmedError = "insufficient_balance"
// SandboxArmIdempotencyReplay makes the next reward command return its prior
// matching result as a replay (Replayed=true) without changing state.
SandboxArmIdempotencyReplay SandboxArmedError = "idempotency_replay"
// SandboxArmIdempotencyConflict fails the next reward command with ErrConflict.
SandboxArmIdempotencyConflict SandboxArmedError = "idempotency_conflict"
)

func SandboxArmedErrors​

func SandboxArmedErrors() []SandboxArmedError

SandboxArmedErrors lists every armable failure mode in display order.

type SandboxCommand​

SandboxCommand is one injected sandbox step. Only the fields for the chosen Kind are read; the rest stay zero.

type SandboxCommand struct {
Kind SandboxCommandKind `json:"kind"`

// AmountCents is the simulated successful deposit amount (deposit).
AmountCents int64 `json:"amount_cents,omitempty"`

// MissionID selects the mission to claim (claim_mission).
MissionID MissionID `json:"mission_id,omitempty"`
// PeriodKey optionally selects the period being claimed (claim_mission,
// claim_weekly_streak). Empty resolves the period the virtual clock makes
// currently claimable, exactly like production claims.
PeriodKey string `json:"period_key,omitempty"`

// RewardChoiceID selects the XP reward choice (claim_xp_reward).
RewardChoiceID string `json:"reward_choice_id,omitempty"`

// ProductID selects the marketplace product (purchase_marketplace).
ProductID string `json:"product_id,omitempty"`

// ForcedOutcomeID forces a roulette outcome by outcome ID instead of rolling
// the seeded RNG (spin_roulette, optional).
ForcedOutcomeID string `json:"forced_outcome_id,omitempty"`

// GrantKind/GrantAmount/GrantReason describe an admin grant (admin_grant).
GrantKind BalanceKind `json:"grant_kind,omitempty"`
GrantAmount int64 `json:"grant_amount,omitempty"`
GrantReason string `json:"grant_reason,omitempty"`

// ClockTo sets the virtual clock to an absolute instant (set_clock).
ClockTo time.Time `json:"clock_to,omitempty"`
// AdvanceBy moves the virtual clock relatively (advance_clock).
AdvanceBy time.Duration `json:"advance_by,omitempty"`

// ArmError arms a failure mode for the next matching command (arm_error).
ArmError SandboxArmedError `json:"arm_error,omitempty"`

// Preset loads a named scenario preset onto a freshly reset session (load_preset).
Preset SandboxPreset `json:"preset,omitempty"`
}

type SandboxCommandKind​

SandboxCommandKind enumerates every injectable sandbox step. Reward commands mirror their production counterparts one-to-one; the remaining kinds are operator controls (clock, armed errors, reset, presets).

type SandboxCommandKind string
const (
SandboxCommandDeposit SandboxCommandKind = "deposit"
SandboxCommandClaimDailyLogin SandboxCommandKind = "claim_daily_login"
SandboxCommandClaimWeeklyStreak SandboxCommandKind = "claim_weekly_streak"
SandboxCommandClaimMission SandboxCommandKind = "claim_mission"
SandboxCommandClaimXPReward SandboxCommandKind = "claim_xp_reward"
SandboxCommandPurchaseMarketplace SandboxCommandKind = "purchase_marketplace"
SandboxCommandSpinRoulette SandboxCommandKind = "spin_roulette"
SandboxCommandAdminGrant SandboxCommandKind = "admin_grant"
SandboxCommandSetClock SandboxCommandKind = "set_clock"
SandboxCommandAdvanceClock SandboxCommandKind = "advance_clock"
SandboxCommandArmError SandboxCommandKind = "arm_error"
// SandboxCommandDisarmErrors clears every armed-and-not-yet-fired failure
// mode without resetting any other session state (operator control).
SandboxCommandDisarmErrors SandboxCommandKind = "disarm_errors"
SandboxCommandReset SandboxCommandKind = "reset"
SandboxCommandLoadPreset SandboxCommandKind = "load_preset"
)

type SandboxLogEntry​

SandboxLogEntry is one append-only event log record: the injected command and the decision the engine took for it.

type SandboxLogEntry struct {
Seq int `json:"seq"`
// At is the virtual clock instant the step ran at.
At time.Time `json:"at"`
Command SandboxCommand `json:"command"`
// Decision is a short human-readable description of the decision taken.
Decision string `json:"decision"`
// Result holds the engine command result for applied (or replayed) reward
// commands; nil for operator controls and rejected commands.
Result *CommandResult `json:"result,omitempty"`
// Error is the typed rejection error string when the command was rejected.
Error string `json:"error,omitempty"`
// ArmedErrorFired names the armed failure mode this step consumed, if any.
ArmedErrorFired SandboxArmedError `json:"armed_error_fired,omitempty"`
}

type SandboxPreset​

SandboxPreset names a scenario preset that loads a session into a meaningful starting state in one action.

type SandboxPreset string
const (
SandboxPresetNewUser SandboxPreset = "new_user"
SandboxPresetDepositActivated SandboxPreset = "deposit_activated"
SandboxPresetXPThresholdFreeplay3 SandboxPreset = "xp_threshold_freeplay_3"
SandboxPresetXPThresholdFreeplay5 SandboxPreset = "xp_threshold_freeplay_5"
SandboxPresetXPThresholdNextDeposit SandboxPreset = "xp_threshold_next_deposit_bonus"
SandboxPresetPendingNextDepositBonus SandboxPreset = "pending_next_deposit_bonus"
SandboxPresetMidDepositStreak SandboxPreset = "mid_deposit_streak"
SandboxPresetClaimableCompletedMissns SandboxPreset = "claimable_completed_missions"
SandboxPresetExpiredMissions SandboxPreset = "expired_missions"
)

func SandboxPresets​

func SandboxPresets() []SandboxPreset

SandboxPresets lists every preset in display order.

type SandboxSnapshot​

SandboxSnapshot is the full session state exposed after every step.

type SandboxSnapshot struct {
SessionID uuid.UUID `json:"session_id"`
// Now is the session's virtual clock.
Now time.Time `json:"now"`
// Seed is the session's roulette RNG seed (sandbox-only math/rand seeding).
Seed int64 `json:"seed"`
Balance Balance `json:"balance"`
DepositActivated bool `json:"deposit_activated"`
// Missions holds derived progress for every mission period with session
// activity plus each mission's current period, in catalog order — produced
// by the same evaluators production uses, with period keys and claimability.
Missions []MissionProgress `json:"missions"`
// WeeklyLoginStreaks covers weeks with daily login claims plus the current
// week, in the same derived read-state shape the missions read model
// exposes (one schema, one evaluator — no thinner sandbox copy).
WeeklyLoginStreaks []WeeklyLoginStreak `json:"weekly_login_streaks"`
// ArmedErrors lists failure modes armed and not yet fired, in arm order.
ArmedErrors []SandboxArmedError `json:"armed_errors"`
EventLog []SandboxLogEntry `json:"event_log"`
}

type SandboxStepResult​

SandboxStepResult is returned by every sandbox step: the updated snapshot and the event log entry describing the decision taken.

type SandboxStepResult struct {
Snapshot SandboxSnapshot `json:"snapshot"`
Entry SandboxLogEntry `json:"entry"`
}

type SignupFreeplayOutcome​

type SignupFreeplayOutcome string
const (
SignupFreeplayGranted SignupFreeplayOutcome = "granted"
SignupFreeplayAlreadyGranted SignupFreeplayOutcome = "already_granted"
SignupFreeplayDisabled SignupFreeplayOutcome = "disabled"
SignupFreeplayNoSubject SignupFreeplayOutcome = "no_subject"
SignupFreeplayNotNew SignupFreeplayOutcome = "not_new_signup"
SignupFreeplaySubjectUsed SignupFreeplayOutcome = "subject_used"
SignupFreeplayNoTouch SignupFreeplayOutcome = "no_qualifying_touch"
SignupFreeplayAbuseGuard SignupFreeplayOutcome = "abuse_guard"
SignupFreeplayBudgetExhausted SignupFreeplayOutcome = "budget_exhausted"
)

type SignupRule​

type SignupRule struct {
Budgets map[SignupRuleOfferKind]SignupRuleBudgetRemaining `json:"budgets,omitempty"`
Version int64 `json:"version"`
Status SignupRuleStatus `json:"status"`
Draft SignupRuleTerms `json:"draft"`
Published *SignupRuleTerms `json:"published,omitempty"`
PublishedVersion *int64 `json:"published_version,omitempty"`
History []SignupRuleChange `json:"history"`
}

type SignupRuleAction​

type SignupRuleAction string
const (
SignupRuleActionMigrate SignupRuleAction = "migrate"
SignupRuleActionSaveDraft SignupRuleAction = "save_draft"
SignupRuleActionPublish SignupRuleAction = "publish"
SignupRuleActionPause SignupRuleAction = "pause"
SignupRuleActionResume SignupRuleAction = "resume"
)

func (SignupRuleAction) Valid​

func (v SignupRuleAction) Valid() bool

type SignupRuleBudgetRemaining​

type SignupRuleBudgetRemaining struct {
DailyCents *int64 `json:"daily_cents,omitempty"`
TotalCents *int64 `json:"total_cents,omitempty"`
}

type SignupRuleChange​

type SignupRuleChange struct {
Version int64 `json:"version"`
Action SignupRuleAction `json:"action"`
At time.Time `json:"at"`
Reason string `json:"reason"`
Actor *string `json:"actor,omitempty"`
}

type SignupRuleCommand​

type SignupRuleCommand struct {
ExpectedVersion int64 `json:"expected_version"`
Action SignupRuleAction `json:"action"`
Terms *SignupRuleTerms `json:"terms,omitempty"`
Reason *string `json:"reason,omitempty"`
PreviewProof *string `json:"preview_proof,omitempty"`
StartsLocal *string `json:"starts_local,omitempty"`
EndsLocal *string `json:"ends_local,omitempty"`
}

type SignupRuleInputError​

SignupRuleInputError identifies the field or action that the editor can correct.

type SignupRuleInputError struct {
Field string
Message string
}

func (SignupRuleInputError) Error​

func (e SignupRuleInputError) Error() string

type SignupRuleOffer​

type SignupRuleOffer struct {
AmountCents int64 `json:"amount_cents"`
PerGrantCents *int64 `json:"per_grant_cents,omitempty"`
PlayerLifetimeCents *int64 `json:"player_lifetime_cents,omitempty"`
PlayerDailyCents *int64 `json:"player_daily_cents,omitempty"`
DailyBudgetCents *int64 `json:"daily_budget_cents,omitempty"`
TotalBudgetCents *int64 `json:"total_budget_cents,omitempty"`
}

type SignupRuleOfferKind​

type SignupRuleOfferKind string
const (
SignupRuleOfferKindStandard SignupRuleOfferKind = "standard"
SignupRuleOfferKindMessenger SignupRuleOfferKind = "messenger"
)

func (SignupRuleOfferKind) Valid​

func (v SignupRuleOfferKind) Valid() bool

type SignupRuleOutcome​

type SignupRuleOutcome string
const (
SignupRuleOutcomeGrant SignupRuleOutcome = "grant"
SignupRuleOutcomeOff SignupRuleOutcome = "off"
SignupRuleOutcomeAlreadyGranted SignupRuleOutcome = "already_granted"
SignupRuleOutcomeBudgetExhausted SignupRuleOutcome = "budget_exhausted"
)

func (SignupRuleOutcome) Valid​

func (v SignupRuleOutcome) Valid() bool

type SignupRulePreview​

type SignupRulePreview struct {
EvaluatedAt time.Time `json:"evaluated_at"`
Version int64 `json:"version"`
Proof string `json:"proof"`
Examples []SignupRulePreviewExample `json:"examples"`
}

type SignupRulePreviewExample​

type SignupRulePreviewExample struct {
Scenario SignupRuleScenario `json:"scenario"`
Outcome SignupRuleOutcome `json:"outcome"`
Offer *SignupRuleOfferKind `json:"offer,omitempty"`
AmountCents int64 `json:"amount_cents"`
DailyRemainingCents *int64 `json:"daily_remaining_cents,omitempty"`
}

type SignupRuleScenario​

type SignupRuleScenario string
const (
SignupRuleScenarioStandard SignupRuleScenario = "standard"
SignupRuleScenarioMessenger SignupRuleScenario = "messenger"
SignupRuleScenarioRepeated SignupRuleScenario = "repeated"
SignupRuleScenarioCapped SignupRuleScenario = "capped"
SignupRuleScenarioDailyCapReached SignupRuleScenario = "daily_cap_reached"
)

func (SignupRuleScenario) Valid​

func (v SignupRuleScenario) Valid() bool

type SignupRuleStatus​

type SignupRuleStatus string
const (
SignupRuleStatusDraft SignupRuleStatus = "draft"
SignupRuleStatusScheduled SignupRuleStatus = "scheduled"
SignupRuleStatusLive SignupRuleStatus = "live"
SignupRuleStatusPaused SignupRuleStatus = "paused"
SignupRuleStatusEnded SignupRuleStatus = "ended"
)

func (SignupRuleStatus) Valid​

func (v SignupRuleStatus) Valid() bool

type SignupRuleTerms​

type SignupRuleTerms struct {
Name string `json:"name"`
Standard *SignupRuleOffer `json:"standard,omitempty"`
Messenger *SignupRuleOffer `json:"messenger,omitempty"`
StartsAt *time.Time `json:"starts_at,omitempty"`
EndsAt *time.Time `json:"ends_at,omitempty"`
}

type SuccessfulDepositCommand​

type SuccessfulDepositCommand struct {
PaymentID uuid.UUID
ActorID uuid.UUID
UserID uuid.UUID
AmountCents int64
OccurredAt time.Time
}

type Summary​

type Summary struct {
Balance Balance
RewardChoices []RewardChoice
MarketplaceProducts []MarketplaceProduct
RouletteOutcomes []RouletteOutcome
}

type WeeklyLoginClaimCommand​

type WeeklyLoginClaimCommand struct {
UserID uuid.UUID
Date time.Time
}

type WeeklyLoginStreak​

WeeklyLoginStreak is the derived weekly login streak read state for one Monday–Sunday New York week (the v1 weekly login XP claim). The weekly streak is NOT a catalog mission — the v1 catalog is fixed at seven IDs — so it rides alongside the mission entries as its own read field. State is derived from daily login claim rows and the weekly claim row; only claims persist (ADR 0003). The sandbox snapshot reuses this exact shape so its embedded production preview renders from the same read state.

type WeeklyLoginStreak struct {
// WeekStart is the week's Monday date "2006-01-02" (the claim identity key).
WeekStart string
// DaysClaimed counts the week's NY days with a daily login claim (0–7).
DaysClaimed int64
Completed bool
State MissionClaimability
PeriodEnd time.Time
ClaimableUntil time.Time // PeriodEnd + grace window (NY calendar days)
// GrantedXP is the fixed config payout of the weekly claim.
GrantedXP int64
}

type XPRewardClaimCommand​

type XPRewardClaimCommand struct {
ActorID uuid.UUID
UserID uuid.UUID
RewardChoiceID string
IdempotencyKey string
}

Generated by gomarkdoc