Skip to main content

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

providers

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

Package providers defines the normalized game-provider integration contract.

Every game provider has its own API, its own vocabulary, and its own opinions. Adapters translate all of that into the single domain language defined here, so admin health, reconciliation, and game-launch controls can be written once instead of once per vendor.

The types cover provider codes, capabilities, kill-switch status, account identifiers, transfer outcomes, launch results, and redacted evidence.

Note that a capability describes what a provider is permitted to do, which is not the same as whether it is working right now. Health answers that, and health can be stale. Code that cares about current behaviour should consult both.

Package providers defines PlayGo's game-provider contract language.

Provider adapters translate vendor wire behavior into these types. They do not decide ledger, wallet, transfer, or admin money state.

Constants​

const (
DefaultInteractiveBalanceReadBudget = 15 * time.Second
DefaultBackgroundBalanceReadBudget = 8 * time.Second
MaxBalanceReadBudget = 30 * time.Second
)
const (
CreateRejectionAuthentication CreateRejectionReason = "provider_authentication"
CreateRejectionUsernameTaken CreateRejectionReason = "username_taken"
CreateRejectionUnknown CreateRejectionReason = "unknown_refusal"
CreateNextCheckAuthentication CreateRejectionNextStep = "check_provider_authentication_then_retry"
CreateNextRetryOrLink CreateRejectionNextStep = "retry_with_new_username_or_link_existing"
CreateNextInspectResponse CreateRejectionNextStep = "inspect_provider_response"
)
const (
MetadataProviderHealthRestore = "provider_health_restore"
MetadataProviderHealthRestoreClose = "close"

ProviderHealthRestoreActionClose ProviderHealthRestoreAction = MetadataProviderHealthRestoreClose
)
const IntegrationFingerprintSetting = "integration_fingerprint"

LegacyPlayerUsernameMaxLen is the cap every generated player username used before providers carried their own limit (game_providers.player_username_max_len); reconcile recomputes pre-evidence creates with it.

const LegacyPlayerUsernameMaxLen = 16

PlayerUsernameMinLen is the shortest generated name every vendor takes: the WS terminal family (Orion Stars, Fire Kirin, Milky Way...) and YOLO need 6.

const PlayerUsernameMinLen = 6

Variables​

var (
ErrInvalidAmountScale = errors.New("invalid provider amount scale")
ErrNegativeAmount = errors.New("negative provider amount")
ErrAmountRemainder = errors.New("provider amount conversion has remainder")
ErrAmountOverflow = errors.New("provider amount conversion overflow")
)
var (
ErrAPIDisabled = errors.New("provider API access is off")
ErrAPIAccessUnavailable = errors.New("provider API access state is unavailable")
)
var (
ErrUnsupportedCapability = errors.New("provider capability unsupported")
ErrCapabilityDisabled = errors.New("provider capability disabled")
ErrCapabilityStatusConflict = errors.New("provider capability status conflict")
ErrProviderNotFound = errors.New("provider not found")
ErrInvalidProviderConfig = errors.New("invalid provider config")
ErrCredentialNotFound = errors.New("provider credential not found")
ErrInvalidCredentialTransition = errors.New("invalid provider credential transition")
ErrTokenNotFound = errors.New("provider token not found")
// ErrProviderNotLive is the ADR 0062 verification fence: a draft or
// verifying provider serves only testers.
ErrProviderNotLive = errors.New("provider_not_live")
)

func APIPausedMessage​

func APIPausedMessage(name string) string

APIPausedMessage is public copy for a deliberate API Off state, not a vendor failure.

func CheckGeneratedPlayerUsername​

func CheckGeneratedPlayerUsername(name ProviderUsername, maxLen int) error

CheckGeneratedPlayerUsername enforces the one rule (ADR 0065) every generated game username follows (#866): lowercase a-z and 0-9 only, a letter first (Juwa, Juwa 2 and Game Vault refuse anything else), and PlayerUsernameMinLen to maxLen characters.

func ClassifyCreateRejection​

func ClassifyCreateRejection(detail OutcomeDetail) (CreateRejectionReason, CreateRejectionNextStep)

func GeneratePlayerPassword​

func GeneratePlayerPassword() (string, error)

GeneratePlayerPassword returns a cryptographically random provider-account password matching the shape providers accept: alphanumeric (no special characters), a fixed length within the providers' accepted range, and guaranteed to contain at least one lowercase letter, one uppercase letter, and one digit. It is used so each provider player account gets a unique password instead of a shared/known value.

func IsAccountRepairVerification​

func IsAccountRepairVerification(ctx context.Context) bool

func IsBackgroundRead​

func IsBackgroundRead(ctx context.Context) bool

IsBackgroundRead reports the adapter admission priority of a read.

func IsProviderHealthRestoreClose​

func IsProviderHealthRestoreClose(metadata map[string]string) bool

func PlayerCredentialAAD​

func PlayerCredentialAAD(accountID uuid.UUID) []byte

PlayerCredentialAAD binds provider login credentials to their account. Every seal and open uses the identical additional authenticated data.

func PlayerUsernameCeiling​

func PlayerUsernameCeiling(family ProviderFamily) int

PlayerUsernameCeiling is the longest generated name a family's players can sign in with, whatever a provider definition says. AgentServer clients cap the login field at 15 (Mafia v1005 EditBox maxLength 15, #851); FastAPI takes 3-16 letters or digits; Juwa and Game Vault are proven at 16. 16 is the shared ceiling for every other family, so one name rule fits every vendor.

func PlayerUsernameLimit​

func PlayerUsernameLimit(family ProviderFamily, definitionMax int) int

PlayerUsernameLimit is the effective maximum for a generated name: the provider definition's limit, never above the family ceiling.

func ProviderHealthRestoreMetadata​

func ProviderHealthRestoreMetadata(action ProviderHealthRestoreAction) map[string]string

func RequireAPIAccess​

func RequireAPIAccess(metadata ProviderMetadata) error

func WithAccountRepairVerification​

func WithAccountRepairVerification(ctx context.Context) context.Context

WithAccountRepairVerification selects the authorized read-only repair path. It bypasses new-import policy only, never balance/session/provider admission.

func WithBackgroundRead​

func WithBackgroundRead(ctx context.Context) context.Context

WithBackgroundRead marks an optional display read. Adapters may defer it without IO to protect pending foreground calls and their shared wire budget. It preserves the caller's cancellation, deadline and tracing context.

type APIAccessAvailability​

type APIAccessAvailability struct {
Mode APIAccessMode
State string
ExpiresAt *time.Time
}

type APIAccessGate​

APIAccessGate provides database-authoritative state. Nil is permitted only for stand-alone adapter fixtures; the application always wires a gate.

type APIAccessGate interface {
Check(context.Context, ProviderCode) error
Availability(context.Context, []ProviderCode) (map[ProviderCode]APIAccessAvailability, error)
}

type APIAccessMode​

type APIAccessMode string
const (
APIAccessOn APIAccessMode = "on"
APIAccessOff APIAccessMode = "off"
)

type AccountActivity​

type AccountActivity struct {
ID uuid.UUID `json:"id"`
Kind AccountActivityKind `json:"kind"`
State AccountActivityState `json:"state"`
Summary string `json:"summary"`
OccurredAt time.Time `json:"occurred_at"`
AmountCents *int64 `json:"amount_cents"`
ProviderCredits *int64 `json:"provider_credits"`
TransferID *uuid.UUID `json:"transfer_id"`
RelatedAccountID *uuid.UUID `json:"related_account_id"`
CommandID *uuid.UUID `json:"command_id"`
ActorID *uuid.UUID `json:"actor_id"`
ActorName *string `json:"actor_name"`
Reason *string `json:"reason"`
NextStep *string `json:"next_step"`
}

type AccountActivityKind​

type AccountActivityKind string
const (
AccountActivityLoad AccountActivityKind = "load"
AccountActivityUnload AccountActivityKind = "unload"
AccountActivityCreditMoveIn AccountActivityKind = "credit_move_in"
AccountActivityCreditMoveOut AccountActivityKind = "credit_move_out"
AccountActivityManagement AccountActivityKind = "management"
AccountActivityProvisioning AccountActivityKind = "provisioning"
AccountActivityPasswordReveal AccountActivityKind = "password_reveal"
AccountActivityPasswordCopy AccountActivityKind = "password_copy_requested"
)

func AccountActivityKinds​

func AccountActivityKinds() []AccountActivityKind

func ParseAccountActivityKind​

func ParseAccountActivityKind(value string) (AccountActivityKind, error)

type AccountActivityPage​

type AccountActivityPage struct {
Items []AccountActivity `json:"items"`
NextCursor *string `json:"next_cursor"`
}

type AccountActivityState​

type AccountActivityState string
const (
ActivityRequested AccountActivityState = "requested"
ActivityWalletDebited AccountActivityState = "wallet_debited"
ActivityProviderRequesting AccountActivityState = "provider_requesting"
ActivityPendingReview AccountActivityState = "pending_review"
ActivityApproved AccountActivityState = "approved"
ActivityRejectRestoring AccountActivityState = "reject_restoring"
ActivityCompleted AccountActivityState = "completed"
ActivityRejected AccountActivityState = "rejected"
ActivityUnknownRequiresReconcile AccountActivityState = "unknown_requires_reconcile"
ActivityFailedInternal AccountActivityState = "failed_internal"
ActivitySourceRequesting AccountActivityState = "source_requesting"
ActivitySourceDebited AccountActivityState = "source_debited"
ActivityDestinationRequesting AccountActivityState = "destination_requesting"
ActivityCompensatingSource AccountActivityState = "compensating_source"
ActivityCompensated AccountActivityState = "compensated"
ActivityNeedsReconcile AccountActivityState = "needs_reconcile"
ActivitySucceeded AccountActivityState = "succeeded"
ActivityUnknown AccountActivityState = "unknown"
ActivityCancelled AccountActivityState = "cancelled"
ActivityResolvedExternally AccountActivityState = "resolved_externally"
ActivityQueued AccountActivityState = "queued"
ActivityRunning AccountActivityState = "running"
ActivityFailed AccountActivityState = "failed"
ActivityUnrecognized AccountActivityState = "unrecognized"
)

func ParseAccountActivityState​

func ParseAccountActivityState(raw string) (AccountActivityState, error)

ParseAccountActivityState accepts persisted owner states, not display labels.

type AccountCreationLookup​

AccountCreationLookup is read-only. NotFound plus a success-like detail proves a complete agent-scoped lookup found no such username. Rejections, partial rosters, malformed payloads and transport failures never establish absence.

type AccountCreationLookup interface {
LookupCreatedPlayer(context.Context, LookupCreatedPlayerRequest) (LookupCreatedPlayerResult, error)
}

type AccountCreator​

type AccountCreator interface {
CreatePlayer(context.Context, CreatePlayerRequest) (CreatePlayerResult, error)
}

type AccountCredentialSummary​

type AccountCredentialSummary struct {
Saved bool `json:"saved"`
Source CredentialProvenance `json:"source"`
VerifiedAt *time.Time `json:"verified_at"`
}

type AccountIssue​

type AccountIssue struct {
Reason AccountIssueReason
Provenance AccountIssueProvenance
}

func AccountIssueForBalance​

func AccountIssueForBalance(detail OutcomeDetail) (AccountIssue, bool)

AccountIssueForBalance never interprets vendor text or the generic invalid_account rejection (which can also mean a local missing credential).

type AccountIssueProvenance​

type AccountIssueProvenance string
const AccountIssueAdapterResponse AccountIssueProvenance = "adapter_response"

type AccountIssueReason​

AccountIssueReason is positive adapter evidence about an external account, independent of PlayGo's operator-controlled account status.

type AccountIssueReason string
const (
AccountIssueNotFound AccountIssueReason = "not_found"
AccountIssueUnreadable AccountIssueReason = "account_unreadable"
AccountIssueCredentialsRejected AccountIssueReason = "credentials_rejected"
)

func (AccountIssueReason) Valid​

func (r AccountIssueReason) Valid() bool

type AccountLinkState​

type AccountLinkState string
const (
AccountLinkLinking AccountLinkState = "linking"
AccountLinkVerified AccountLinkState = "verified"
AccountLinkFailed AccountLinkState = "failed"
)

type AccountManagementAction​

type AccountManagementAction struct {
Enabled bool `json:"enabled"`
DisabledReason *string `json:"disabled_reason,omitempty"`
Requirements AccountManagementRequirements `json:"requirements"`
NextStep string `json:"next_step"`
RetryPolicy AccountManagementRetryPolicy `json:"retry_policy"`
}

type AccountManagementActions​

type AccountManagementActions struct {
AccessSavedPassword *AccountManagementAction `json:"access_saved_password,omitempty"`
RefreshBalance *AccountManagementAction `json:"refresh_balance,omitempty"`
VerifyCurrentPassword AccountManagementAction `json:"verify_current_password"`
ResetPassword AccountManagementAction `json:"reset_password"`
RecordPanelPassword AccountManagementAction `json:"record_panel_password"`
RetryLinkVerification AccountManagementAction `json:"retry_link_verification"`
UnlinkPreview AccountManagementAction `json:"unlink_preview"`
}

type AccountManagementAudit​

type AccountManagementAudit struct {
ID uuid.UUID `json:"id"`
ActorID uuid.UUID `json:"actor_id"`
CommandID uuid.UUID `json:"command_id"`
Operation AccountManagementOperation `json:"operation"`
Outcome AccountManagementOutcome `json:"outcome"`
BeforeRevision *int64 `json:"before_revision"`
AfterRevision *int64 `json:"after_revision"`
Reason string `json:"reason"`
CreatedAt time.Time `json:"created_at"`
RetryID *uuid.UUID `json:"retry_id"`
PreviewID *uuid.UUID `json:"preview_id"`
ResolvedCommandID *uuid.UUID `json:"resolved_command_id"`
}

type AccountManagementBalance​

type AccountManagementBalance struct {
Credits *int64 `json:"credits"`
ObservedAt *time.Time `json:"observed_at"`
Issue *AccountIssueReason `json:"issue"`
// CreditsNotLoadedBeforeLoad is admin advisory only (ADR 0018, 2026-11-10):
// the current cycle includes credits that were in the game, not loaded
// through the app, when its first load was admitted.
CreditsNotLoadedBeforeLoad *AccountManagementCreditsNotLoaded `json:"credits_not_loaded_before_load,omitempty"`
}

type AccountManagementCredentialCommand​

type AccountManagementCredentialCommand struct {
CommandID uuid.UUID `json:"command_id"`
Outcome AccountManagementOutcome `json:"outcome"`
OwnerActive bool `json:"owner_active"`
ResetDispatched bool `json:"reset_dispatched"`
}

type AccountManagementCreditsNotLoaded​

AccountManagementCreditsNotLoaded is the verified balance a load preflight froze before the current cycle's first load. Cents is computed by Postgres.

type AccountManagementCreditsNotLoaded struct {
TransferID uuid.UUID `json:"transfer_id"`
Credits int64 `json:"credits"`
Cents int64 `json:"cents"`
LoadedAt time.Time `json:"loaded_at"`
}

type AccountManagementError​

type AccountManagementError struct{ Reason AccountManagementReason }

func (AccountManagementError) Error​

func (e AccountManagementError) Error() string

type AccountManagementExpected​

AccountManagementExpected witnesses identity and credentials independently of ordinary balance observations. Nil revision matches only an absent version.

type AccountManagementExpected struct {
ManagementRevision *int64 `json:"management_revision"`
IdentityFingerprint string `json:"identity_fingerprint"`
CredentialID *uuid.UUID `json:"credential_id"`
CredentialUpdatedAt *time.Time `json:"credential_updated_at"`
ProvisioningID *uuid.UUID `json:"provisioning_id"`
ProvisioningUpdatedAt *time.Time `json:"provisioning_updated_at"`
}

type AccountManagementIdentity​

type AccountManagementIdentity struct {
AccountID uuid.UUID `json:"account_id"`
UserID uuid.UUID `json:"user_id"`
ProviderCode ProviderCode `json:"provider_code"`
Reference string `json:"reference"`
Username string `json:"username"`
PlayerID *string `json:"player_id"`
Status AccountStatus `json:"status"`
}
type AccountManagementLink struct {
StartedAt *time.Time `json:"started_at"`
DeadlineAt *time.Time `json:"deadline_at"`
State *AccountLinkState `json:"state"`
FailureCode *string `json:"failure_code"`
FailedAt *time.Time `json:"failed_at"`
ActiveSuccessorID *uuid.UUID `json:"active_successor_id"`
}

type AccountManagementOperation​

type AccountManagementOperation string
const (
ManagementLinkExisting AccountManagementOperation = "link_existing"
ManagementVerifyCurrentPassword AccountManagementOperation = "verify_current_password"
ManagementResetPassword AccountManagementOperation = "reset_password"
ManagementRecordPanelPassword AccountManagementOperation = "record_panel_password"
ManagementRetryLinkVerification AccountManagementOperation = "retry_link_verification"
ManagementUnlinkPreview AccountManagementOperation = "unlink_preview"
ManagementCancelUnlinkPreview AccountManagementOperation = "cancel_unlink_preview"
ManagementUnlink AccountManagementOperation = "unlink"
)

func AccountManagementOperations​

func AccountManagementOperations() []AccountManagementOperation

func (AccountManagementOperation) Valid​

func (p AccountManagementOperation) Valid() bool

type AccountManagementOutcome​

type AccountManagementOutcome string
const (
ManagementRequested AccountManagementOutcome = "requested"
ManagementSucceeded AccountManagementOutcome = "succeeded"
ManagementRejected AccountManagementOutcome = "rejected"
ManagementUnknown AccountManagementOutcome = "unknown"
ManagementCancelled AccountManagementOutcome = "cancelled"
ManagementResolvedExternally AccountManagementOutcome = "resolved_externally"
)

func AccountManagementOutcomes​

func AccountManagementOutcomes() []AccountManagementOutcome

func (AccountManagementOutcome) Valid​

func (p AccountManagementOutcome) Valid() bool

type AccountManagementReason​

type AccountManagementReason string
const (
ManagementPasswordUnavailable AccountManagementReason = "saved_password_unavailable"
ManagementSavedLoginUnreadable AccountManagementReason = "credential_unreadable"
)
const (
ManagementVersionConflict AccountManagementReason = "version_conflict"
ManagementCapabilityUnavailable AccountManagementReason = "capability_unavailable"
ManagementCurrentPasswordRequired AccountManagementReason = "current_password_required"
ManagementBusy AccountManagementReason = "account_management_busy"
ManagementActiveSuccessorExists AccountManagementReason = "active_successor_exists"
ManagementLinkAttemptInProgress AccountManagementReason = "link_attempt_in_progress"
ManagementBalanceNotZero AccountManagementReason = "balance_not_zero"
ManagementBalanceUnverified AccountManagementReason = "balance_unverified"
ManagementPreviewRequired AccountManagementReason = "preview_required"
ManagementPreviewExpired AccountManagementReason = "preview_expired"
ManagementPreviewOwnerMismatch AccountManagementReason = "preview_owner_mismatch"
ManagementPanelAttestationRequired AccountManagementReason = "panel_attestation_required"
ManagementPanelIdentityMismatch AccountManagementReason = "panel_identity_mismatch"
ManagementCommandResolvedExternally AccountManagementReason = "command_resolved_externally"
)

func AccountManagementReasons​

func AccountManagementReasons() []AccountManagementReason

func (AccountManagementReason) Valid​

func (p AccountManagementReason) Valid() bool

type AccountManagementRequirements​

type AccountManagementRequirements struct {
ReasonRequired bool `json:"reason_required"`
PasswordRequired bool `json:"password_required"`
CurrentPasswordRequired bool `json:"current_password_required"`
PanelConfirmationsRequired bool `json:"panel_confirmations_required"`
EvidenceRequired bool `json:"evidence_required"`
FreshZeroPreviewRequired bool `json:"fresh_zero_preview_required"`
}

type AccountManagementRetryPolicy​

type AccountManagementRetryPolicy string
const (
ManagementRetrySameRequest AccountManagementRetryPolicy = "same_request"
ManagementRetryNewRequestAfterReview AccountManagementRetryPolicy = "new_request_after_review"
ManagementRetryNoRetry AccountManagementRetryPolicy = "no_retry"
)

type AccountManagementSetupHistory​

type AccountManagementSetupHistory struct {
ID uuid.UUID `json:"id"`
State AccountProvisioningState `json:"state"`
Archived bool `json:"archived"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
JobIDs []uuid.UUID `json:"job_ids"`
}

type AccountManagementSnapshot​

type AccountManagementSnapshot struct {
AsOf time.Time `json:"as_of"`
Expected AccountManagementExpected `json:"expected"`
Identity AccountManagementIdentity `json:"identity"`
Credential AccountCredentialSummary `json:"credential"`
Options AccountRepairOptions `json:"options"`
Actions AccountManagementActions `json:"actions"`
Audit []AccountManagementAudit `json:"audit"`
SetupHistory []AccountManagementSetupHistory `json:"setup_history"`
Balance AccountManagementBalance `json:"balance"`
Link AccountManagementLink `json:"link"`
CredentialCommand *AccountManagementCredentialCommand `json:"credential_command"`
}

type AccountProvisioningState​

type AccountProvisioningState string
const (
AccountProvisioningQueued AccountProvisioningState = "queued"
AccountProvisioningRunning AccountProvisioningState = "running"
AccountProvisioningSucceeded AccountProvisioningState = "succeeded"
AccountProvisioningFailed AccountProvisioningState = "failed"
AccountProvisioningUnknown AccountProvisioningState = "unknown_requires_reconcile"
)

func ParseAccountProvisioningState​

func ParseAccountProvisioningState(value string) (AccountProvisioningState, error)

type AccountRepairCapabilities​

AccountRepairCapabilities describes actual read-only verification, independently of whether new account imports are enabled by store policy.

type AccountRepairCapabilities interface{ AccountRepairOptions() AccountRepairOptions }

type AccountRepairOptions​

AccountRepairCapabilities describes actual read-only verification, independently of whether new account imports are enabled by store policy.

type AccountRepairOptions struct {
Verification AccountRepairVerification `json:"verification"`
Password PlayerLinkPasswordRequirement `json:"password"`
ReconnectEnabled bool `json:"reconnect_enabled"`
SetPasswordEnabled bool `json:"set_password_enabled"`
ResetPasswordEnabled bool `json:"reset_password_enabled"`
ResetRequiresCurrentPassword bool `json:"reset_requires_current_password"`
ResetResultKind PasswordResetResultKind `json:"reset_result_kind"`
}

func (AccountRepairOptions) CanReconnectWithPassword​

func (o AccountRepairOptions) CanReconnectWithPassword() bool

CanReconnectWithPassword is the capability for replacing a player's saved login.

type AccountRepairVerification​

type AccountRepairVerification string
const (
RepairCredentialRead AccountRepairVerification = "credential_read" // #nosec G101 -- Public contract enum label, not credential material.
RepairAgentRoster AccountRepairVerification = "agent_roster"
RepairBalanceReadOnly AccountRepairVerification = "balance_read_only"
RepairVerificationUnavailable AccountRepairVerification = "unavailable"
)

type AccountStatus​

AccountStatus is the lifecycle of a persisted provider account.

type AccountStatus string
const (
AccountStatusLinking AccountStatus = "linking"
AccountStatusActive AccountStatus = "active"
AccountStatusDisabled AccountStatus = "disabled"
AccountStatusLinkFailed AccountStatus = "link_failed"
AccountStatusUnlinked AccountStatus = "unlinked"
)

type AgentBalanceReader​

type AgentBalanceReader interface {
ReadAgentBalance(context.Context, ReadAgentBalanceRequest) (ReadAgentBalanceResult, error)
}

type AmountPolicy​

type AmountPolicy interface {
CashToProvider(CashCents) (ProviderCredits, error)
ProviderToCash(ProviderCredits) (CashCents, error)
FormatWire(ProviderCredits) (string, error)
ParseWire(string) (ProviderCredits, error)
}

type BalanceReadBudget​

type BalanceReadBudget struct {
Interactive time.Duration `mapstructure:"interactive"`
Background time.Duration `mapstructure:"background"`
}

type BalanceReadBudgets​

type BalanceReadBudgets struct {
Interactive time.Duration `mapstructure:"interactive"`
Background time.Duration `mapstructure:"background"`
Providers map[ProviderCode]BalanceReadBudget `mapstructure:"providers"`
}

func (BalanceReadBudgets) For​

func (b BalanceReadBudgets) For(code ProviderCode) BalanceReadBudget

func (BalanceReadBudgets) MaxBackground​

func (b BalanceReadBudgets) MaxBackground() time.Duration

type BalanceReader​

type BalanceReader interface {
ReadPlayerBalance(context.Context, ReadPlayerBalanceRequest) (ReadPlayerBalanceResult, error)
}

type CallStage​

CallStage names canonical diagnostic phases, never vendor endpoints.

type CallStage string
const (
StageSessionWait CallStage = "session_wait"
StageAgentLogin CallStage = "agent_login"
StageBalancePreRead CallStage = "balance_pre_read"
StageCreditAck CallStage = "credit_ack"
StageDebitAck CallStage = "debit_ack"
StageBalancePostRead CallStage = "balance_post_read"
)

type Capability​

type Capability string
const (
CapabilityCreatePlayer Capability = "create_player"
CapabilityCredit Capability = "credit"
CapabilityDebit Capability = "debit"
CapabilityBalance Capability = "balance"
CapabilityLaunch Capability = "launch"
CapabilityResetPassword Capability = "reset_password"
CapabilityTransferFind Capability = "transfer_find"
CapabilityTransferList Capability = "transfer_list"
CapabilityGameLog Capability = "game_log"
CapabilityAgentBalance Capability = "agent_balance"
CapabilityForcePlayerOffline Capability = "force_player_offline"
CapabilityPlayerLink Capability = "player_link"
CapabilityPlayerList Capability = "player_list"
)

type CapabilityStatus​

type CapabilityStatus string
const (
CapabilityStatusEnabled CapabilityStatus = "enabled"
CapabilityStatusDisabled CapabilityStatus = "disabled"
CapabilityStatusDegraded CapabilityStatus = "degraded"
CapabilityStatusReconciliationOnly CapabilityStatus = "reconciliation_only"
)

func (CapabilityStatus) Allows​

func (s CapabilityStatus) Allows(c Capability) bool

func (CapabilityStatus) Valid​

func (s CapabilityStatus) Valid() bool

type CapabilityStatusChange​

type CapabilityStatusChange struct {
ProviderCode ProviderCode
Capability Capability
ExpectedStatus CapabilityStatus
NextStatus CapabilityStatus
ActorRef string
Reason string
}

type CapabilityStatusTransition​

type CapabilityStatusTransition struct {
ProviderCode ProviderCode
Capability Capability
PreviousStatus CapabilityStatus
NextStatus CapabilityStatus
ActorRef string
Reason string
}

type CashCents​

type CashCents int64

type CreatePlayerRequest​

type CreatePlayerRequest struct {
ProviderCode ProviderCode
RequestedUsername ProviderUsername
CredentialMaterial SecretMaterial
CredentialVisibility *CredentialVisibility
IdempotencyKeyRef IdempotencyKeyRef
Metadata map[string]string
}

type CreatePlayerResult​

type CreatePlayerResult struct {
Detail OutcomeDetail
Success *CreatePlayerSuccess
}

type CreatePlayerSuccess​

type CreatePlayerSuccess struct {
// NewlyCreated is an adapter's positive create proof, never a roster adoption.
NewlyCreated bool
ProviderPlayerAccountRef ProviderPlayerAccountRef
SubmittedUsername ProviderUsername
ProviderPlayerID *ProviderPlayerID
ProviderFullAccount *string
CredentialRef *ProviderCredentialRef
CredentialMaterial SecretMaterial
CredentialVisibility CredentialVisibility
}

type CreateRejectionNextStep​

type CreateRejectionNextStep string

func (CreateRejectionNextStep) Valid​

func (s CreateRejectionNextStep) Valid() bool

type CreateRejectionReason​

CreateRejectionReason describes only definitive no-create results, not an uncertain mutation or a player credential issue.

type CreateRejectionReason string

func (CreateRejectionReason) Valid​

func (r CreateRejectionReason) Valid() bool

type CredentialProvenance​

type CredentialProvenance string
const (
CredentialLegacyUnknown CredentialProvenance = "legacy_unknown"
CredentialPlayerSuppliedUnverified CredentialProvenance = "player_supplied_unverified"
CredentialNativePasswordVerified CredentialProvenance = "native_password_verified"
CredentialNativeCreationConfirmed CredentialProvenance = "native_creation_confirmed"
CredentialNativeResetConfirmed CredentialProvenance = "native_reset_confirmed"
CredentialStaffPanelAttested CredentialProvenance = "staff_panel_attested" // #nosec G101 -- Public contract enum label, not credential material.
)

func CredentialProvenances​

func CredentialProvenances() []CredentialProvenance

func (CredentialProvenance) Valid​

func (p CredentialProvenance) Valid() bool

type CredentialPurpose​

type CredentialPurpose string
const (
CredentialPurposeAPI CredentialPurpose = "api"
CredentialPurposeLaunch CredentialPurpose = "launch"
CredentialPurposePlayer CredentialPurpose = "player"
)

type CredentialRecord​

type CredentialRecord struct {
ProviderCode ProviderCode
Purpose CredentialPurpose
Version CredentialVersion
Status CredentialStatus
Value CredentialValue
CreatedAt time.Time
ActivatedAt *time.Time
}

type CredentialStatus​

type CredentialStatus string
const (
CredentialStatusPending CredentialStatus = "pending"
CredentialStatusActive CredentialStatus = "active"
CredentialStatusInactive CredentialStatus = "inactive"
)

type CredentialStatusChange​

type CredentialStatusChange struct {
ProviderCode ProviderCode
Purpose CredentialPurpose
Version CredentialVersion
ExpectedStatus CredentialStatus
NextStatus CredentialStatus
ActorRef string
Reason string
}

type CredentialStatusTransition​

type CredentialStatusTransition struct {
ProviderCode ProviderCode
Purpose CredentialPurpose
Version CredentialVersion
PreviousStatus CredentialStatus
NextStatus CredentialStatus
ActorRef string
Reason string
}

type CredentialStore​

type CredentialStore interface {
GetActive(context.Context, ProviderCode, CredentialPurpose) (CredentialRecord, error)
PutPending(context.Context, PutPendingCredentialRequest) (CredentialRecord, error)
Activate(context.Context, CredentialStatusChange) (CredentialRecord, error)
Deactivate(context.Context, CredentialStatusChange) error
}

type CredentialValue​

type CredentialValue struct {
Ref ProviderCredentialRef
Material SecretMaterial
}

type CredentialVersion​

type CredentialVersion string

type CredentialVisibility​

type CredentialVisibility string
const (
CredentialVisibilityHidden CredentialVisibility = "hidden"
CredentialVisibilityUserVisible CredentialVisibility = "user_visible"
CredentialVisibilityRequiredManual CredentialVisibility = "required_manual"
)

type CreditPlayerRequest​

type CreditPlayerRequest struct {
ProviderCode ProviderCode
ProviderPlayerAccountRef ProviderPlayerAccountRef
ExternalOrderID ExternalOrderID
Credits ProviderCredits
Reason string
IdempotencyKeyRef IdempotencyKeyRef
Metadata map[string]string
}

type DebitPlayerRequest​

type DebitPlayerRequest struct {
ProviderCode ProviderCode
ProviderPlayerAccountRef ProviderPlayerAccountRef
ExternalOrderID ExternalOrderID
Credits ProviderCredits
Reason string
IdempotencyKeyRef IdempotencyKeyRef
Metadata map[string]string
}

type DiagnosticLoginProber​

type DiagnosticLoginProber interface {
ProbeLogin(context.Context) (OutcomeDetail, error)
}

type DiagnosticRead​

DiagnosticRead deliberately exposes no player identity or mutation method. Adapters own their pure read dispatch and protocol recipes.

type DiagnosticRead struct {
ID DiagnosticStepID
Label string
Implemented bool
Required bool
Citation string
SignatureCode string
}

func DiagnosticReads​

func DiagnosticReads(login, balance bool, recipe string) []DiagnosticRead

DiagnosticReads is an adapter descriptor builder, not a capability inference from runtime flags. The caller selects only adapter-declared reads.

type DiagnosticReader​

type DiagnosticReader interface {
ReadDiagnostic(context.Context, DiagnosticStepID) (OutcomeDetail, error)
}

type DiagnosticStepID​

type DiagnosticStepID string
const (
DiagnosticReadLogin DiagnosticStepID = "read_login"
DiagnosticAgentBalanceStep DiagnosticStepID = "agent_balance"
DiagnosticStoreInfo DiagnosticStepID = "store_info"
DiagnosticGameList DiagnosticStepID = "game_list"
DiagnosticPlayerLookup DiagnosticStepID = "player_lookup"
DiagnosticCreate DiagnosticStepID = "create"
DiagnosticInitialBalance DiagnosticStepID = "initial_balance"
DiagnosticLoad DiagnosticStepID = "load"
DiagnosticLoadedBalance DiagnosticStepID = "loaded_balance"
DiagnosticUnload DiagnosticStepID = "unload"
DiagnosticFinalBalance DiagnosticStepID = "final_balance"
DiagnosticReset DiagnosticStepID = "reset"
DiagnosticCredentialVerify DiagnosticStepID = "credential_verify" // #nosec G101 -- a diagnostic step code, not a credential.
DiagnosticLinkVerify DiagnosticStepID = "link_verify"
DiagnosticCleanup DiagnosticStepID = "cleanup"
)

type EndpointRedirectError​

EndpointRedirectError preserves response facts when admission refuses a redirect after dispatch. It never proves that the operation was not applied. Scheme and Host contain only the target origin, never credentials or a query.

type EndpointRedirectError struct {
HTTPStatus int
Scheme string
Host string
}

func (EndpointRedirectError) Error​

func (EndpointRedirectError) Error() string

type ExternalOrderID​

type ExternalOrderID string

type FailureCategory​

FailureCategory is adapter-classified, low-cardinality diagnostic evidence. It never carries a vendor message, URL, credential or response payload.

type FailureCategory string
const (
FailureTimeout FailureCategory = "timeout"
FailureTransport FailureCategory = "transport"
FailureDecode FailureCategory = "decode"
FailureAuth FailureCategory = "auth"
FailureUpstream FailureCategory = "upstream_error"
FailureInvalidAccount FailureCategory = "invalid_account"
FailureCredentialsRejected FailureCategory = "credentials_rejected"
FailureUnsupported FailureCategory = "unsupported"
FailureCanceled FailureCategory = "canceled"
// FailureDeferred is adapter-proven local admission with no HTTP attempt.
FailureDeferred FailureCategory = "deferred"
)

func BalanceFailureCategory​

func BalanceFailureCategory(detail OutcomeDetail) FailureCategory

BalanceFailureCategory consumes canonical evidence only. Unknown/custom adapters still get a bounded category, never a heuristic over their messages.

func (FailureCategory) Valid​

func (c FailureCategory) Valid() bool

type FindTransferRequest​

type FindTransferRequest struct {
ProviderCode ProviderCode
ExternalOrderID ExternalOrderID
Metadata map[string]string
}

type FindTransferResult​

type FindTransferResult struct {
Detail OutcomeDetail
Finding TransferFinding
Observation *TransferObservation
// HistorySearchEndsAt is the end of a complete no-match search window.
// Nil means the adapter did not establish such a window.
HistorySearchEndsAt *time.Time
}

type ForcePlayerOfflineRequest​

type ForcePlayerOfflineRequest struct {
ProviderCode ProviderCode
ProviderPlayerAccountRef ProviderPlayerAccountRef
IdempotencyKeyRef IdempotencyKeyRef
Metadata map[string]string
}

type ForcePlayerOfflineResult​

type ForcePlayerOfflineResult struct {
Detail OutcomeDetail
}

type GameLauncher​

type GameLauncher interface {
LaunchGame(context.Context, LaunchGameRequest) (LaunchGameResult, error)
}

type GameRecord​

type GameRecord struct {
ProviderPlayerAccountRef ProviderPlayerAccountRef
GameRef GameRef
ProviderRecordID string
StartedAt time.Time
EndedAt time.Time
NetCredits ProviderCredits
Evidence ProviderEvidence
}

type GameRecordLister​

type GameRecordLister interface {
ListGameRecords(context.Context, ListGameRecordsRequest) (ListGameRecordsResult, error)
}

type GameRef​

type GameRef string

type HTTPCallTiming​

HTTPCallTiming contains durations only. Nil means the hook was not observed (for example DNS/TLS on a reused connection), not zero or a fabricated phase.

type HTTPCallTiming struct {
ElapsedMillis int64
DNSMillis *int64 `json:",omitempty"`
ConnectMillis *int64 `json:",omitempty"`
TLSMillis *int64 `json:",omitempty"`
TTFBMillis *int64 `json:",omitempty"`
ServerWaitMillis *int64 `json:",omitempty"`
ConnectionReused *bool `json:",omitempty"`
}

type IdempotencyKeyRef​

type IdempotencyKeyRef string

type IntegrationFingerprint​

type IntegrationFingerprint string

type LaunchGameRequest​

type LaunchGameRequest struct {
ProviderCode ProviderCode
ProviderPlayerAccountRef ProviderPlayerAccountRef
GameRef GameRef
ReturnURL string
ClientIP string
Locale string
IdempotencyKeyRef IdempotencyKeyRef
Metadata map[string]string
}

type LaunchGameResult​

type LaunchGameResult struct {
Detail OutcomeDetail
Success *LaunchGameSuccess
}

type LaunchGameSuccess​

type LaunchGameSuccess struct {
LaunchMode *LaunchMode
RedirectURL *string
EmbeddedHTML *string
CredentialRef *ProviderCredentialRef
ExpiresAt *time.Time
}

type LaunchMode​

type LaunchMode string
const (
LaunchModeRedirectURL LaunchMode = "redirect_url"
LaunchModeEmbeddedHTML LaunchMode = "embedded_html"
LaunchModeManualCredentials LaunchMode = "manual_credentials"
LaunchModeUnsupported LaunchMode = "unsupported"
)

type LinearAmountPolicy​

type LinearAmountPolicy struct {
CashCentsPerProviderCredit CashCents
WireScale ProviderCredits
}

func OneToOneAmountPolicy​

func OneToOneAmountPolicy() LinearAmountPolicy

func (LinearAmountPolicy) CashToProvider​

func (p LinearAmountPolicy) CashToProvider(cents CashCents) (ProviderCredits, error)

func (LinearAmountPolicy) FormatWire​

func (p LinearAmountPolicy) FormatWire(credits ProviderCredits) (string, error)

func (LinearAmountPolicy) ParseWire​

func (p LinearAmountPolicy) ParseWire(value string) (ProviderCredits, error)

func (LinearAmountPolicy) ProviderToCash​

func (p LinearAmountPolicy) ProviderToCash(credits ProviderCredits) (CashCents, error)

type LinkProof​

LinkProof records how strongly a verifier tied the account to our agent.

type LinkProof string
const (
// LinkProofAgentScopedLookup: an agent-scoped player lookup found the account.
LinkProofAgentScopedLookup LinkProof = "agent_scoped_lookup"
// LinkProofCredentialVerified: an agent-signed call accepted the player's password.
LinkProofCredentialVerified LinkProof = "credential_verified" // #nosec G101 -- proof kind, not a credential
// LinkProofAgentSignedBalanceRead: only an agent-signed balance read succeeded.
LinkProofAgentSignedBalanceRead LinkProof = "agent_signed_balance_read"
)

func (LinkProof) Valid​

func (p LinkProof) Valid() bool

type ListGameRecordsRequest​

type ListGameRecordsRequest struct {
ProviderCode ProviderCode
ProviderPlayerAccountRef ProviderPlayerAccountRef
GameRef GameRef
From *time.Time
To *time.Time
Cursor *RecordCursor
Limit *int
Metadata map[string]string
}

type ListGameRecordsResult​

type ListGameRecordsResult struct {
Detail OutcomeDetail
Records []GameRecord
NextCursor *RecordCursor
}

type ListPlayersRequest​

type ListPlayersRequest struct {
ProviderCode ProviderCode
Cursor *RecordCursor
Limit int
}

type ListPlayersResult​

A successful page is not proof that the roster is complete. The collector must validate total stability, distinct identities and the terminal page.

type ListPlayersResult struct {
Detail OutcomeDetail
Players []RosterPlayer
Total *int
NextCursor *RecordCursor
}

type ListTransferRecordsRequest​

type ListTransferRecordsRequest struct {
ProviderCode ProviderCode
From *time.Time
To *time.Time
Cursor *RecordCursor
Limit *int
Metadata map[string]string
}

type ListTransferRecordsResult​

type ListTransferRecordsResult struct {
Detail OutcomeDetail
Records []TransferObservation
NextCursor *RecordCursor
}

type LookupCreatedPlayerRequest​

type LookupCreatedPlayerRequest struct {
ProviderCode ProviderCode
RequestedUsername ProviderUsername
// CredentialMaterial is the password sealed before the create was sent,
// for vendors whose only lookup needs the player's password. It is empty
// when no such password was held; a lookup must then not guess one.
CredentialMaterial SecretMaterial
}

type LookupCreatedPlayerResult​

type LookupCreatedPlayerResult struct {
Detail OutcomeDetail
Finding PlayerLookupFinding
Success *CreatePlayerSuccess
}

type MissingPasswordPage​

type MissingPasswordPage struct {
Items []MissingPasswordTask
NextCursor *uuid.UUID
}

type MissingPasswordTask​

type MissingPasswordTask struct {
AccountID uuid.UUID
UserID uuid.UUID
PlayerName string
ProviderCode ProviderCode
Username string
Procedure PasswordRecoveryProcedure
NextStep string
}

type NoDispatchError​

NoDispatchError is issued by a transport that refused this request before dispatch. A plain network or access error alone is not dispatch evidence.

type NoDispatchError struct{ Cause error }

func (NoDispatchError) Error​

func (e NoDispatchError) Error() string

func (NoDispatchError) Unwrap​

func (e NoDispatchError) Unwrap() error

type ObservationConfidence​

type ObservationConfidence string
const (
ObservationConfidenceDirectOrder ObservationConfidence = "direct_order"
ObservationConfidenceTradeRecord ObservationConfidence = "trade_record"
ObservationConfidenceBalanceDelta ObservationConfidence = "balance_delta"
ObservationConfidenceManualEvidence ObservationConfidence = "manual_evidence"
)

type Operation​

type Operation string
const (
OperationProviderGames Operation = "provider_games"
OperationFindPlayer Operation = "find_player"
OperationListPlayers Operation = "list_players"
OperationVerifyExisting Operation = "verify_existing_player"
OperationCreatePlayer Operation = "create_player"
OperationCreditPlayer Operation = "credit_player"
OperationDebitPlayer Operation = "debit_player"
OperationReadPlayerBalance Operation = "read_player_balance"
OperationReadAgentBalance Operation = "read_agent_balance"
OperationLaunchGame Operation = "launch_game"
OperationResetPlayerPassword Operation = "reset_player_password"
OperationForcePlayerOffline Operation = "force_player_offline"
OperationFindTransfer Operation = "find_transfer"
OperationListTransferRecord Operation = "list_transfer_records"
OperationListGameRecord Operation = "list_game_records"
)

func (Operation) String​

func (op Operation) String() string

type Outcome​

type Outcome string
const (
OutcomeSucceeded Outcome = "succeeded"
OutcomeRejected Outcome = "rejected"
OutcomeDuplicateSucceeded Outcome = "duplicate_succeeded"
OutcomeDuplicateRejected Outcome = "duplicate_rejected"
OutcomeUnknown Outcome = "unknown"
OutcomeUnsupported Outcome = "unsupported"
)

func (Outcome) FinalForProviderCall​

func (o Outcome) FinalForProviderCall() bool

func (Outcome) IsSuccessLike​

func (o Outcome) IsSuccessLike() bool

func (Outcome) String​

func (outcome Outcome) String() string

type OutcomeDetail​

type OutcomeDetail struct {
Outcome Outcome
RejectionCode RejectionCode
Message string
Evidence ProviderEvidence
}

func DiagnosticBalance​

func DiagnosticBalance(ctx context.Context, client AgentBalanceReader, code ProviderCode) (OutcomeDetail, error)

func DiagnosticLogin​

func DiagnosticLogin(ctx context.Context, client DiagnosticLoginProber) (OutcomeDetail, error)

func DuplicateRejected​

func DuplicateRejected(code RejectionCode, message string, e ProviderEvidence) OutcomeDetail

func DuplicateSucceeded​

func DuplicateSucceeded(e ProviderEvidence) OutcomeDetail

func Rejected​

func Rejected(code RejectionCode, message string, e ProviderEvidence) OutcomeDetail

func Succeeded​

func Succeeded(e ProviderEvidence) OutcomeDetail

func TransferPrerequisiteFailed​

func TransferPrerequisiteFailed(detail OutcomeDetail) OutcomeDetail

TransferPrerequisiteFailed describes a failed login or admission step before the first money request. Reads and unrelated operations keep their original classification.

func TransportFailure​

func TransportFailure(message string, e ProviderEvidence) OutcomeDetail

TransportFailure is for the primary request's transport error only. Unknown intentionally never promotes a follow-up failure into a mutation refusal.

func Unknown​

func Unknown(message string, e ProviderEvidence) OutcomeDetail

func Unsupported​

func Unsupported(message string, e ProviderEvidence) OutcomeDetail

type PanelURL​

PanelURL is a provider's operator back-office URL.

type PanelURL = panelurl.URL

type PasswordAccessPurpose​

type PasswordAccessPurpose string
const (
PasswordAccessReveal PasswordAccessPurpose = "reveal"
PasswordAccessCopy PasswordAccessPurpose = "copy"
)

type PasswordRecoveryProcedure​

type PasswordRecoveryProcedure string
const (
PasswordProcedureNativeReset PasswordRecoveryProcedure = "native_reset"
PasswordProcedurePanelReset PasswordRecoveryProcedure = "panel_reset"
PasswordProcedureCurrentOrPanel PasswordRecoveryProcedure = "current_password_or_panel"
PasswordProcedureOriginalReset PasswordRecoveryProcedure = "original_reset_recovery"
)

type PasswordResetResultKind​

type PasswordResetResultKind string
const (
ResetPasswordMaterial PasswordResetResultKind = "password_material" // #nosec G101 -- Public contract enum label, not credential material.
ResetCredentialReference PasswordResetResultKind = "credential_reference" // #nosec G101 -- Public contract enum label, not credential material.
ResetResultUnavailable PasswordResetResultKind = "unavailable" // #nosec G101 -- Public contract enum label, not credential material.
)

type PasswordResetter​

type PasswordResetter interface {
ResetPlayerPassword(context.Context, ResetPlayerPasswordRequest) (ResetPlayerPasswordResult, error)
}

type PlayerLinkForm​

PlayerLinkForm is backend-owned "Add existing" form metadata per provider.

type PlayerLinkForm struct {
IdentifierLabel string
Password PlayerLinkPasswordRequirement
}

type PlayerLinkPasswordRequirement​

PlayerLinkPasswordRequirement describes native verification credential handling. Existing-account link/relink separately require capture for encrypted storage.

type PlayerLinkPasswordRequirement string
const (
// PlayerLinkPasswordRequired: verification needs the password (e.g. terminal
// providers such as MilkyWay authenticate queryInfo with it).
PlayerLinkPasswordRequired PlayerLinkPasswordRequirement = "required"
// PlayerLinkPasswordOptional: native identity verification works without it.
PlayerLinkPasswordOptional PlayerLinkPasswordRequirement = "optional"
// PlayerLinkPasswordNotAccepted: native verification does not consume it;
// link/relink still capture and store it as unverified on identity success.
PlayerLinkPasswordNotAccepted PlayerLinkPasswordRequirement = "not_accepted"
)

func (PlayerLinkPasswordRequirement) Valid​

func (r PlayerLinkPasswordRequirement) Valid() bool

type PlayerLinkVerifier​

PlayerLinkVerifier verifies, with read-only provider calls only, that an existing provider account (created outside PlayGo) is reachable under our agent and reports its current balance. It never creates, credits, debits, or changes the password of the account. Verification proves agent ownership; it does not prove which PlayGo player owns the account.

type PlayerLinkVerifier interface {
VerifyExistingPlayer(context.Context, VerifyExistingPlayerRequest) (VerifyExistingPlayerResult, error)
}

type PlayerLookupFinding​

PlayerLookupFinding is an explicit proof; a missing success payload alone never establishes that another create is safe.

type PlayerLookupFinding string
const (
PlayerLookupFound PlayerLookupFinding = "found"
PlayerLookupNotFound PlayerLookupFinding = "not_found"
PlayerLookupUnknown PlayerLookupFinding = "unknown"
)

type PlayerOfflineForcer​

type PlayerOfflineForcer interface {
ForcePlayerOffline(context.Context, ForcePlayerOfflineRequest) (ForcePlayerOfflineResult, error)
}

type PlayerRosterReader​

PlayerRosterReader lists the authenticated agent's registered players. It is distinct from a lookup of one known account or a low-deposit subset.

type PlayerRosterReader interface {
ListPlayers(context.Context, ListPlayersRequest) (ListPlayersResult, error)
}

type ProviderClient​

type ProviderClient interface {
ProviderCode() ProviderCode
}

type ProviderCode​

type ProviderCode string
const (
ProviderCodeFastAPIVBlink ProviderCode = "vblink"
ProviderCodeFastAPIUltraPanda ProviderCode = "ultrapanda"
ProviderCodeFastAPIDragonFury ProviderCode = "dragonfury"
ProviderCodeFastAPIUltraThunder ProviderCode = "ultrathunder"
ProviderCodeFastAPIGoldenTreasure ProviderCode = "goldentreasure"
ProviderCodeFastAPIGlamourSpin ProviderCode = "glamourspin"
ProviderCodeFastAPIEgame ProviderCode = "egame"
ProviderCodeWSTerminalMilkyWay ProviderCode = "milkyway"
ProviderCodeWSTerminalKraken ProviderCode = "kraken"
ProviderCodeGameVault ProviderCode = "gamevault"
ProviderCodeJuwa ProviderCode = "juwa"
ProviderCodeJuwa2 ProviderCode = "juwa2"
ProviderCodeBlueDragon ProviderCode = "bluedragon"
ProviderCodeRiverPay ProviderCode = "riverpay"
ProviderCodeCashier ProviderCode = "cashier"
ProviderCodeSlotopool ProviderCode = "slotopool"
ProviderCodeGoldenDragon ProviderCode = "goldendragon"
ProviderCodeVPower ProviderCode = "vpower"
ProviderCodePandaMaster ProviderCode = "pandamaster"
ProviderCodeCashFrenzy ProviderCode = "cashfrenzy777"
ProviderCodeCashMachine ProviderCode = "cashmachine"
ProviderCodeGameroom ProviderCode = "gameroom"
ProviderCodeMrAllInOne ProviderCode = "mrallinone"
ProviderCodeMafia ProviderCode = "mafia"
ProviderCodeNoble ProviderCode = "noble"
ProviderCodeWinStar ProviderCode = "winstar"
ProviderCodeLuckyStars ProviderCode = "luckystars"
ProviderCodeVegasX ProviderCode = "vegasx"
ProviderCodeOrionStars ProviderCode = "orionstars"
ProviderCodeFireKirin ProviderCode = "firekirin"
ProviderCodeVegasSweeps ProviderCode = "vegassweeps"
ProviderCodeMegaSpin ProviderCode = "megaspin"
ProviderCodeLuckyStrike ProviderCode = "luckystrike"
ProviderCodeKingOfPop ProviderCode = "kingofpop"
ProviderCodeSuperDragon ProviderCode = "superdragon"
ProviderCodeYolo ProviderCode = "yolo"
)

func (ProviderCode) String​

func (code ProviderCode) String() string

type ProviderConfig​

type ProviderConfig struct {
Metadata ProviderMetadata
AmountPolicy AmountPolicy
Settings map[string]string
}

type ProviderConfigStore​

type ProviderConfigStore interface {
GetConfig(context.Context, ProviderCode) (ProviderConfig, error)
ListConfigs(context.Context) ([]ProviderConfig, error)
SetCapabilityStatus(context.Context, CapabilityStatusChange) (ProviderConfig, error)
}

type ProviderCredentialRef​

type ProviderCredentialRef string

type ProviderCredits​

type ProviderCredits int64

func ParseObservedCredits​

func ParseObservedCredits(scalar any, unitsPerCredit string, multiplier int64) (ProviderCredits, error)

ParseObservedCredits normalizes exact vendor units before flooring once. unitsPerCredit is the adapter's exact policy quote; multiplier accounts for the vendor endpoint's documented unit scale. It never parses request amounts.

type ProviderEvidence​

type ProviderEvidence struct {
// CreateSentAfterAbsenceProof marks an unknown create whose insert was sent
// only after the adapter proved the name absent and that the vendor did not
// refuse as a duplicate: an account later found under this name holds the
// password this create sent. Without it a found name proves identity only.
CreateSentAfterAbsenceProof bool `json:",omitempty"`
// NoOutboundRefusal proves this HTTP request was not dispatched; it does not classify an earlier mutation.
NoOutboundRefusal RejectionCode `json:",omitempty"`
// CommandNotDispatched proves the command stopped before dispatch, even
// when a prerequisite such as login made its own HTTP request.
CommandNotDispatched bool `json:",omitempty"`
RejectionCode RejectionCode `json:",omitempty"`
// AccountReadIsolated is adapter-proven same-session auth and fresh other-account read evidence.
AccountReadIsolated bool

// ReadDeferred records optional adapter admission that issued no vendor IO.
ReadDeferredReason ReadDeferralReason `json:",omitempty"`
ReadDeferred bool `json:",omitempty"`
VendorFailure *VendorFailureDiagnostic `json:",omitempty"`
FailureCategory FailureCategory
ProviderCode ProviderCode
Operation Operation
RequestID *string
ExternalOrderID *ExternalOrderID
HTTPStatus *int
ProviderStatus string
ProviderMessage string
RawRequest *RedactedPayload
RawResponse *RedactedPayload
LatencyMillis *int64
TraceID *TraceID
StageTimings []StageTiming `json:",omitempty"`
TimingsTruncated bool `json:",omitempty"`
ObservedAt *time.Time
RedactionVersion string
}

func (ProviderEvidence) WithFailureCategory​

func (e ProviderEvidence) WithFailureCategory(category FailureCategory) ProviderEvidence

func (ProviderEvidence) WithObservedAt​

func (e ProviderEvidence) WithObservedAt(now time.Time) ProviderEvidence

type ProviderFamily​

type ProviderFamily string
const (
ProviderFamilyFastAPI ProviderFamily = "fastapi"
ProviderFamilyWSTerminal ProviderFamily = "wsterminal"
ProviderFamilyGameVault ProviderFamily = "gamevault"
ProviderFamilyJuwa ProviderFamily = "juwa"
ProviderFamilyBlueDragon ProviderFamily = "bluedragon"
ProviderFamilyRiverPay ProviderFamily = "riverpay"
ProviderFamilyCashier ProviderFamily = "cashier"
ProviderFamilyAgentServer ProviderFamily = "agentserver"
ProviderFamilySlotopool ProviderFamily = "slotopool"
ProviderFamilyYolo ProviderFamily = "yolo"
)

type ProviderHealthRestoreAction​

type ProviderHealthRestoreAction string

func ProviderHealthRestoreActionFromMetadata​

func ProviderHealthRestoreActionFromMetadata(metadata map[string]string) (ProviderHealthRestoreAction, bool)

type ProviderMetadata​

type ProviderMetadata struct {
APIAccess *APIAccessAvailability
// AgentBalanceRequiresLogin is adapter-owned protocol knowledge, not a provider-name rule.
AgentBalanceRequiresLogin bool
Code ProviderCode
Family ProviderFamily
DisplayName string
Capabilities map[Capability]CapabilityStatus
DefaultGameRef GameRef
// PlayerLinkForm describes the "Add existing" form for adapters that
// implement PlayerLinkVerifier; nil when linking is not supported.
PlayerLinkForm *PlayerLinkForm
// TransferVerification is how an operator verifies a transfer in this
// provider's panel; the adapter declares it. Nil when undescribed.
TransferVerification *TransferVerification
// PanelURL is the operator back-office URL from the integration config;
// nil when not configured.
PanelURL *PanelURL
}

func ApplyLiveMutationGate​

func ApplyLiveMutationGate(metadata ProviderMetadata, enabled bool) ProviderMetadata

func (ProviderMetadata) CapabilityStatus​

func (m ProviderMetadata) CapabilityStatus(capability Capability) (CapabilityStatus, bool)

func (ProviderMetadata) Clone​

func (m ProviderMetadata) Clone() ProviderMetadata

Clone returns a deep copy, so a registry can hand metadata out without sharing its maps, slices or pointers.

type ProviderOrderID​

type ProviderOrderID string

type ProviderPlayerAccountRef​

type ProviderPlayerAccountRef string

type ProviderPlayerID​

type ProviderPlayerID string

type ProviderSlotExpected​

type ProviderSlotExpected struct {
OccupyingAccountID *uuid.UUID `json:"occupying_account_id"`
ProvisioningID *uuid.UUID `json:"provisioning_id"`
ProvisioningUpdatedAt *time.Time `json:"provisioning_updated_at"`
}

type ProviderTransactionRef​

type ProviderTransactionRef string

type ProviderUsername​

type ProviderUsername string

type PutPendingCredentialRequest​

type PutPendingCredentialRequest struct {
ProviderCode ProviderCode
Purpose CredentialPurpose
Version CredentialVersion
Value CredentialValue
}

type ReadAgentBalanceRequest​

type ReadAgentBalanceRequest struct {
ProviderCode ProviderCode
Metadata map[string]string
}

type ReadAgentBalanceResult​

type ReadAgentBalanceResult struct {
Detail OutcomeDetail
BalanceCredits *ProviderCredits
}

type ReadCadence​

ReadCadence controls automatic scheduling only; money and explicit reads never wait on it.

type ReadCadence interface {
Record(context.Context, ProviderCode, bool, time.Time)
PlayerInterval(context.Context, ProviderCode, time.Time) time.Duration
AgentInterval(context.Context, ProviderCode, time.Time) time.Duration
}

type ReadCadenceConfig​

type ReadCadenceConfig struct {
FailureThresholdBps int `mapstructure:"failure_threshold_bps"`
MinimumSamples int `mapstructure:"minimum_samples"`
Window time.Duration `mapstructure:"window"`
}

type ReadDeferralReason​

type ReadDeferralReason string
const ReadDeferralSessionBusy ReadDeferralReason = "session_busy"

type ReadPlayerBalanceRequest​

type ReadPlayerBalanceRequest struct {
ProviderCode ProviderCode
ProviderPlayerAccountRef ProviderPlayerAccountRef
Metadata map[string]string
}

type ReadPlayerBalanceResult​

type ReadPlayerBalanceResult struct {
Detail OutcomeDetail
BalanceCredits *ProviderCredits
}

type RecordCursor​

type RecordCursor string

type RedactedPayload​

type RedactedPayload string

type Registry​

type Registry interface {
Resolve(context.Context, ProviderCode) (ResolvedProvider, error)
List(context.Context) ([]ProviderMetadata, error)
}

type RejectionCode​

type RejectionCode string
const (
RejectionAPIDisabled RejectionCode = "provider_api_disabled"
RejectionAPIAccessUnavailable RejectionCode = "provider_api_unavailable"
)
const (
RejectionUnsupportedCapability RejectionCode = "unsupported_capability"
RejectionCapabilityDisabled RejectionCode = "capability_disabled"
RejectionInvalidAccount RejectionCode = "invalid_account"
RejectionAccountNotFound RejectionCode = "account_not_found"
RejectionAccountUnreadable RejectionCode = "account_unreadable"
RejectionCredentialsRejected RejectionCode = "credentials_rejected"
RejectionInvalidAmount RejectionCode = "invalid_amount"
RejectionInvalidCursor RejectionCode = "invalid_cursor"
RejectionInvalidOrderID RejectionCode = "invalid_order_id"
RejectionInvalidLimit RejectionCode = "invalid_limit"
RejectionAgentBalanceLow RejectionCode = "agent_balance_low"
RejectionProviderInsufficient RejectionCode = "provider_insufficient_balance"
RejectionProviderBusiness RejectionCode = "provider_business_rejection"
RejectionDuplicateMismatch RejectionCode = "duplicate_mismatch"
RejectionDuplicateUsername RejectionCode = "duplicate_username"
// RejectionCredentialRequired: the provider needs the player's password to
// verify an existing account and none (or the wrong one) was supplied.
RejectionCredentialRequired RejectionCode = "credential_required" // #nosec G101 -- rejection code, not a credential
// RejectionPlayerInGame: the provider refused a credit move while the player
// is inside a game; it succeeds after they return to the game lobby.
RejectionPlayerInGame RejectionCode = "player_in_game"
)

func (RejectionCode) RefusesCreditForAgentFloat​

func (c RejectionCode) RefusesCreditForAgentFloat() bool

RefusesCreditForAgentFloat reports whether a load refusal indicates an insufficient store balance. On an unload the same code can mean player funds.

type ResetPlayerPasswordRequest​

type ResetPlayerPasswordRequest struct {
ProviderCode ProviderCode
ProviderPlayerAccountRef ProviderPlayerAccountRef
IdempotencyKeyRef IdempotencyKeyRef
CurrentCredentialMaterial SecretMaterial
NewCredentialMaterial SecretMaterial
}

type ResetPlayerPasswordResult​

type ResetPlayerPasswordResult struct {
Detail OutcomeDetail
Success *ResetPlayerPasswordSuccess
}

type ResetPlayerPasswordSuccess​

type ResetPlayerPasswordSuccess struct {
ProviderPlayerAccountRef ProviderPlayerAccountRef
CredentialRef *ProviderCredentialRef
CredentialMaterial SecretMaterial
}

type ResolvedProvider​

type ResolvedProvider struct {
Metadata ProviderMetadata
Client ProviderClient
// Captured atomically with this client. Nil means no verified integration
// identity, so store-target management must remain unavailable.
IntegrationFingerprint *IntegrationFingerprint
}

type RosterPlayer​

type RosterPlayer struct {
ProviderPlayerAccountRef ProviderPlayerAccountRef
ProviderPlayerID ProviderPlayerID
Username ProviderUsername
BalanceCredits *ProviderCredits
// LastSeen stays nil when the vendor does not document its timezone.
LastSeen *time.Time
}

type SecretMaterial​

type SecretMaterial struct {
// contains filtered or unexported fields
}

func CreationPassword​

func CreationPassword(requested SecretMaterial, username, stableUsername string, stablePassword SecretMaterial) (SecretMaterial, error)

CreationPassword honors a command-owned, durably sealed candidate. Direct adapter probes still use the stable canary password or a fresh player secret.

func NewSecretMaterial​

func NewSecretMaterial(value string) SecretMaterial

func PlayerAccountPassword​

func PlayerAccountPassword(normalizedUsername, normalizedStableUsername string, stablePassword SecretMaterial) (SecretMaterial, error)

PlayerAccountPassword returns the password to set when provisioning a provider player account: the configured stable test password for the probe/canary account (when the normalized requested username equals the normalized stable test username), or a fresh cryptographically random password for every real player. Sharing one password across players is a cross-account takeover vector, so real players never reuse the stable/probe password.

func (SecretMaterial) Empty​

func (s SecretMaterial) Empty() bool

func (SecretMaterial) GoString​

func (s SecretMaterial) GoString() string

func (SecretMaterial) Reveal​

func (s SecretMaterial) Reveal() string

func (SecretMaterial) String​

func (s SecretMaterial) String() string

type StageTiming​

type StageTiming struct {
Stage CallStage
ElapsedMillis int64
FailureCategory FailureCategory `json:",omitempty"`
HTTPCalls []HTTPCallTiming `json:",omitempty"`
}

type TokenCache​

type TokenCache interface {
Get(context.Context, ProviderCode, TokenKind) (TokenRecord, error)
CompareAndSwap(context.Context, TokenCompareAndSwapRequest) (*TokenRecord, bool, error)
Delete(context.Context, ProviderCode, TokenKind) error
}

type TokenCompareAndSwapRequest​

type TokenCompareAndSwapRequest struct {
ProviderCode ProviderCode
Kind TokenKind
ExpectedVersion *string
CreateIfMissing bool
Next TokenRecord
}

type TokenKind​

type TokenKind string
const (
TokenKindAgent TokenKind = "agent"
TokenKindLaunch TokenKind = "launch"
TokenKindPlayerSession TokenKind = "player_session"
)

type TokenRecord​

type TokenRecord struct {
ProviderCode ProviderCode
Kind TokenKind
Token SecretMaterial
Version string
ExpiresAt *time.Time
UpdatedAt time.Time
}

type TraceID​

type TraceID string

type TransferDirection​

type TransferDirection string
const (
TransferDirectionCredit TransferDirection = "credit"
TransferDirectionDebit TransferDirection = "debit"
)

type TransferFinder​

type TransferFinder interface {
FindTransfer(context.Context, FindTransferRequest) (FindTransferResult, error)
}

type TransferFinding​

type TransferFinding string
const (
TransferFindingFound TransferFinding = "found"
TransferFindingMissing TransferFinding = "missing"
TransferFindingUnknown TransferFinding = "unknown"
)

type TransferLookupKey​

TransferLookupKey names a PlayGo-held identifier an operator can search a provider's own panel by to find one load or cash-out. An adapter lists only the identifiers it actually sends to the provider unchanged.

type TransferLookupKey string
const (
// TransferLookupExternalOrderID is PlayGo's order id for the transfer,
// sent to the provider verbatim.
TransferLookupExternalOrderID TransferLookupKey = "external_order_id"
// TransferLookupPlayerAccountRef is the provider's id for the player's
// account, as PlayGo stores it.
TransferLookupPlayerAccountRef TransferLookupKey = "player_account_ref"
// TransferLookupPlayerUsername is the player's game username.
TransferLookupPlayerUsername TransferLookupKey = "player_username"
)

type TransferMatchField​

TransferMatchField names what an operator compares on the panel record once found, to tell whether it is the transfer in question.

type TransferMatchField string
const (
TransferMatchDirection TransferMatchField = "direction"
// TransferMatchCredits is the credit amount, as the panel shows credits.
TransferMatchCredits TransferMatchField = "credits"
// TransferMatchCashAmount is the dollar amount, for panels that move
// money in dollars rather than credits.
TransferMatchCashAmount TransferMatchField = "cash_amount"
TransferMatchTime TransferMatchField = "time"
)

type TransferObservation​

type TransferObservation struct {
ExternalOrderID ExternalOrderID
ProviderOrderID ProviderOrderID
ProviderTransactionRef ProviderTransactionRef
ProviderPlayerAccountRef ProviderPlayerAccountRef
Direction TransferDirection
Credits ProviderCredits
Outcome Outcome
Confidence ObservationConfidence
ProviderObservedAt time.Time
Evidence ProviderEvidence
}

type TransferRecordLister​

type TransferRecordLister interface {
ListTransferRecords(context.Context, ListTransferRecordsRequest) (ListTransferRecordsResult, error)
}

type TransferResult​

type TransferResult struct {
Detail OutcomeDetail
ExternalOrderID ExternalOrderID
Success *TransferSuccess
}

type TransferSuccess​

type TransferSuccess struct {
ProviderOrderID ProviderOrderID
BalanceAfterCredits *ProviderCredits
ProviderTransactionRef *ProviderTransactionRef
}

type TransferVerification​

TransferVerification is how an operator verifies a transfer in the provider's own panel: what to search by, in the order most likely to find exactly one record, and what to compare once found. It describes a procedure only; it never says what the outcome was.

type TransferVerification struct {
LookupKeys []TransferLookupKey
MatchFields []TransferMatchField
}

func CashTransferVerification​

func CashTransferVerification(lookupKeys ...TransferLookupKey) *TransferVerification

CashTransferVerification is the procedure for a panel that moves money in dollars rather than credits: compare direction, dollar amount and time.

func CreditTransferVerification​

func CreditTransferVerification(lookupKeys ...TransferLookupKey) *TransferVerification

CreditTransferVerification is the procedure for a panel that shows transfers in credits: search by the given keys, then compare direction, credits and time. Each call returns a fresh value.

func (*TransferVerification) Clone​

func (v *TransferVerification) Clone() *TransferVerification

Clone returns a deep copy; nil stays nil.

type UnlinkPreviewState​

type UnlinkPreviewState string
const (
UnlinkPreviewReady UnlinkPreviewState = "ready"
UnlinkPreviewBlocked UnlinkPreviewState = "blocked"
UnlinkPreviewConsumed UnlinkPreviewState = "consumed"
UnlinkPreviewCancelled UnlinkPreviewState = "cancelled"
UnlinkPreviewExpired UnlinkPreviewState = "expired"
)

type VendorFailureDiagnostic​

VendorFailureDiagnostic holds adapter-selected and sanitized failure text. It is separate from raw audit evidence and never changes provider outcomes.

type VendorFailureDiagnostic struct {
StatusCode string
BodyStatusCode string `json:",omitempty"`
Message string
}

type VerifyExistingPlayerRequest​

type VerifyExistingPlayerRequest struct {
ProviderCode ProviderCode
// AccountIdentifier is the player-supplied username or provider account ref.
AccountIdentifier string
// CredentialMaterial is the player's password when the provider needs it.
CredentialMaterial SecretMaterial
}

type VerifyExistingPlayerResult​

type VerifyExistingPlayerResult struct {
// Absent is positive native lookup evidence, never a credential rejection inference.
Absent bool

Detail OutcomeDetail
Success *VerifyExistingPlayerSuccess
}

type VerifyExistingPlayerSuccess​

VerifyExistingPlayerSuccess is only returned together with a success-like outcome. Observed balances are floored to whole provider credits.

type VerifyExistingPlayerSuccess struct {
ProviderPlayerAccountRef ProviderPlayerAccountRef
Username ProviderUsername
ProviderPlayerID *ProviderPlayerID
BalanceCredits ProviderCredits
Proof LinkProof
}

type WalletCreditor​

type WalletCreditor interface {
CreditPlayer(context.Context, CreditPlayerRequest) (TransferResult, error)
}

type WalletDebitor​

type WalletDebitor interface {
DebitPlayer(context.Context, DebitPlayerRequest) (TransferResult, error)
}

Generated by gomarkdoc