@rbxts/scribe 2.5.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/types/common.d.ts CHANGED
@@ -1,355 +1,357 @@
1
- import type { BigValue, Disconnect } from "./schema";
2
-
3
- /** Arbitrary stored or external data is unknown until the caller validates it. */
4
- export type UnknownRecord = { [key: string]: unknown };
5
- export type PathSegment = string | number;
6
- export type Path = ReadonlyArray<PathSegment>;
7
- export type OpKind = "Init" | "Set" | "Insert" | "Remove" | "Clear";
8
- export interface Op { Kind: OpKind; Path: Path; Value?: unknown; Index?: number; }
9
-
10
- /** Transport functions are genuine colon methods; accessor/API functions are not. */
11
- export interface ScribeTransport {
12
- readonly Name: string;
13
- readonly MaxFrameBytes?: number;
14
- SendToClient(player: Player, bytes: buffer): void;
15
- SendToAllClients?(bytes: buffer): void;
16
- ListenServer(callback: (this: void, player: Player, bytes: buffer) => void): void;
17
- SendToServer(bytes: buffer): void;
18
- ListenClient(callback: (this: void, bytes: buffer) => void): void;
19
- Release?(): void;
20
- }
21
-
22
- export interface Connection {
23
- readonly Connected: boolean;
24
- Disconnect(): void;
25
- }
26
- /** Read-only event surface. Scribe owns firing and destroying these signals. */
27
- export interface Signal<Args extends unknown[]> {
28
- Connect(callback: (this: void, ...args: Args) => void): Connection;
29
- Once(callback: (this: void, ...args: Args) => void): Connection;
30
- Wait(): LuaTuple<Args>;
31
- }
32
-
33
- export type LogLevel = "Debug" | "Info" | "Warn" | "Error" | "Fatal";
34
- /** Each sink has its own severity filter and bounded callback queue. */
35
- export interface LogSinkOptions { Level?: LogLevel; MaxQueued?: number; }
36
- export type LogCategory = "Persistence" | "Replication" | "Transport" | "Commands" | "Leaderboards" | "Monetization" | "Gifting" | "Integrity" | "Lifecycle" | "Derived" | "Exchanges";
37
- /** Public diagnostic codes, kept in sync with src/Types.luau. */
38
- export type LogCode =
39
- | "DATASTORE_CRITICAL"
40
- | "DATASTORE_RECOVERED"
41
- | "EXPORT_ENCODE_FAIL"
42
- | "LEGACY_IMPORTED"
43
- | "LEGACY_IMPORT_FAIL"
44
- | "MIGRATED"
45
- | "MESSAGE_SEND_FAIL"
46
- | "MESSAGE_QUEUE_FULL"
47
- | "MESSAGE_NO_LISTENER"
48
- | "MESSAGE_HANDLER_ERROR"
49
- | "MESSAGE_HANDLER_STALLED"
50
- | "MIGRATION_FAIL"
51
- | "MIGRATION_RECONCILE_DEPENDENT"
52
- | "MIGRATION_RESERVED_DISCARDED"
53
- | "MODE_OVERRIDES_LEGACY"
54
- | "OFFLINE_READ_FAIL"
55
- | "OFFLINE_WRITE_FAIL"
56
- | "NOSAVE_WRITE_REFUSED"
57
- | "PROFILE_ERASED"
58
- | "PROFILE_ERASE_FAIL"
59
- | "PROFILE_ERASE_PROGRESS_FAIL"
60
- | "PROFILE_ERASE_RESUMED"
61
- | "PROFILE_LOADED"
62
- | "PROFILE_LOAD_FAIL"
63
- | "PROFILE_RESET"
64
- | "PROFILE_RESTORED"
65
- | "PROFILE_RESTORE_FAIL"
66
- | "RESTORE_RESERVED_PRESERVED"
67
- | "PROFILE_SIZE"
68
- | "SLOW_LOAD"
69
- | "SLOW_IMPORT"
70
- | "SAVE_WAIT_TIMEOUT"
71
- | "PROFILE_STORE_ERROR"
72
- | "PROFILE_STORE_SIGNAL_MISSING"
73
- | "PROFILE_TOO_LARGE"
74
- | "PROFILE_UNPERSISTABLE"
75
- | "PROFILE_VERSION_AHEAD"
76
- | "SAVE_INTERVAL_CLAMPED"
77
- | "WIPE_GUARD_RATIO_CLAMPED"
78
- | "HEALTH_THRESHOLDS_CONFLICT"
79
- | "SAVE_INTERVAL_CONFLICT"
80
- | "SAVE_INTERVAL_FAIL"
81
- | "SAVE_INTERVAL_SET"
82
- | "SHUTDOWN_DONE"
83
- | "SHUTDOWN_FLUSH"
84
- | "SIM_LOAD_FAILURE"
85
- | "SIM_SESSION_STEAL"
86
- | "STATUS_CHANGED"
87
- | "UNKNOWN_ROOT_KEYS"
88
- | "VERSION_QUERY_FAIL"
89
- | "VERSION_READ_FAIL"
90
- | "ANALYTICS_FAIL"
91
- | "ANOMALY"
92
- | "ECONOMY_FIELDS_OVERFLOW"
93
- | "ECONOMY_FIELD_UNDECLARED"
94
- | "PROFILE_OVERWRITTEN"
95
- | "PROFILE_TOO_DEEP"
96
- | "PROFILE_SCHEMA_VIOLATION"
97
- | "TIMED_SWEEP_FAIL"
98
- | "WIPE_GUARD_BLOCKED"
99
- | "WIPE_GUARD_CLEARED"
100
- | "WIPE_GUARD_FORCED"
101
- | "WIPE_GUARD_TRIPPED"
102
- | "CLIENT_HANDSHAKE_TIMEOUT"
103
- | "FRAGMENT_REFUSED"
104
- | "INIT_APPLIED"
105
- | "INIT_SEND_FAIL"
106
- | "MIRROR_RESYNC"
107
- | "INIT_SENT"
108
- | "INIT_UNDELIVERED"
109
- | "OP_BEFORE_INIT"
110
- | "OUTBOUND_OVERSIZE"
111
- | "PROTOCOL_MISMATCH"
112
- | "SCHEMA_MISMATCH"
113
- | "SERIALIZE_FAIL"
114
- | "SNAPSHOT_ROOT_DROPPED"
115
- | "INBOUND_OVERSIZE"
116
- | "INBOUND_OVERSIZE_LIMIT"
117
- | "INBOUND_RATE_LIMITED"
118
- | "INBOUND_WORK_LIMIT"
119
- | "MALFORMED_FRAME"
120
- | "MALFORMED_FRAME_LIMIT"
121
- | "SEND_FAIL"
122
- | "COMMAND_BAD_ARGS"
123
- | "COMMAND_BAD_IDEMPOTENCY_KEY"
124
- | "COMMAND_ERROR"
125
- | "COMMAND_IDEM_EVICTED"
126
- | "COMMAND_IDEM_SATURATED"
127
- | "COMMAND_RATE_LIMITED"
128
- | "COMMAND_REPLY_ENCODE_FAIL"
129
- | "COMMAND_REPLY_TRUNCATED"
130
- | "COMMAND_UNKNOWN"
131
- | "SIM_COMMAND"
132
- | "GRANT_FAIL"
133
- | "GRANT_PARTIAL"
134
- | "GRANT_SEEDED_ELEMENT"
135
- | "RECEIPT_IN_FLIGHT"
136
- | "RECEIPT_HISTORY_FULL"
137
- | "OWNERSHIP_CHECK_FAIL"
138
- | "PASS_PURCHASE_UNCONFIRMED"
139
- | "PERK_GRANTED"
140
- | "PERK_REVOKED"
141
- | "PRODUCT_INFO_FAIL"
142
- | "POLICY_READ_FAIL"
143
- | "PAID_RANDOM_RECEIPT"
144
- | "PRODUCT_INFO_THROTTLED"
145
- | "PURCHASE_DUPLICATE"
146
- | "PURCHASE_CLAIM_EVICTED"
147
- | "PURCHASE_ID_EVICTED"
148
- | "RECEIPT_DUPLICATE"
149
- | "RECEIPT_GRANTED"
150
- | "RECEIPT_HANDLER_BOUND"
151
- | "RECEIPT_OFFLINE_RETRY"
152
- | "RECEIPT_RETRY"
153
- | "RECEIPT_UNKNOWN_PRODUCT"
154
- | "SIM_RECEIPT"
155
- | "UNDECLARED_CATEGORY"
156
- | "UNDECLARED_PERK"
157
- | "UNKNOWN_OWNS_KEY"
158
- | "GIFT_AIM_CAP_REACHED"
159
- | "GIFT_AIM_EXPIRED"
160
- | "GIFT_AIM_SETTLED"
161
- | "GIFT_CREDIT_ISSUED"
162
- | "GIFT_CREDIT_REFUND_FAIL"
163
- | "GIFT_CREDIT_UNCONFIRMED"
164
- | "GIFT_CREDIT_UNKNOWN_PRODUCT"
165
- | "GIFT_CREDIT_USED"
166
- | "GIFT_DELIVERY_RETRY"
167
- | "GIFT_INTENT_EXPIRED"
168
- | "GIFT_INTENT_WRITE_FAIL"
169
- | "GIFT_INVALID_RECIPIENT"
170
- | "GIFT_NO_INTENT"
171
- | "GIFT_RECEIPT_GRANTED"
172
- | "GIFT_RECIPIENT_ALREADY_OWNS"
173
- | "GIFT_UNKNOWN_PRODUCT"
174
- | "RECEIPT_DECLINED_PENDING_CREDIT"
175
- | "RECEIPT_HELD"
176
- | "LB_ERASE_FAIL"
177
- | "LB_INTERVAL_CLAMPED"
178
- | "LB_QUEUE_OVERFLOW"
179
- | "LB_READ_FAIL"
180
- | "LB_SCORE_OUT_OF_RANGE"
181
- | "LB_SHUTDOWN_FLUSH"
182
- | "LB_STAT_RESOLVE_FAIL"
183
- | "LB_UNKNOWN_BOARD"
184
- | "LB_BUDGET_DEFERRED"
185
- | "LB_WRITE_DROPPED"
186
- | "LB_WRITE_FAIL"
187
- | "SIM_LB_FLUSH"
188
- | "EXCHANGE_INIT_TAMPER"
189
- | "EXCHANGE_PARKED"
190
- | "EXCHANGE_REGISTRATION_REFUSED"
191
- | "EXCHANGE_RESET_REFUSED"
192
- | "EXCHANGE_RESOLVED"
193
- | "EXCHANGE_RESOLVE_ERROR"
194
- | "EXCHANGE_STORE_UNAVAILABLE"
195
- | "EXCHANGE_UNRESOLVED"
196
- | "DERIVED_ERROR"
197
- | "DERIVED_FEEDBACK"
198
- | "DERIVED_MISMATCH"
199
- | "API_NAME_COLLISION"
200
- | "DEBUG_HOOK_ATTACHED"
201
- | "DEBUG_HOOK_ATTRIBUTION"
202
- | "DEBUG_HOOK_DUPLICATE"
203
- | "DEBUG_HOOK_ERROR"
204
- | "DEBUG_HOOK_FAIL"
205
- | "DEBUG_HOOK_WRITES"
206
- | "DEV_WARNING"
207
- | "DYNAMIC_DEFAULT_FAILED"
208
- | "LISTENER_ERROR"
209
- | "ON_PLAYER_INIT_ERROR"
210
- | "PLAYER_LEAVING_HOOK_SLOW"
211
- | "SANDBOXED"
212
- | "SERVER_STARTED"
213
- | "SIM_STATUS"
214
- | "SUBSYSTEM_HOOK_ERROR"
215
- | "UNKNOWN_OPTION";
216
- export interface LogEntry {
217
- At: number;
218
- Level: LogLevel;
219
- Category: LogCategory;
220
- Code: LogCode;
221
- Message: string;
222
- Context?: UnknownRecord;
223
- }
224
- export interface LogFilter { Level?: LogLevel; Category?: LogCategory; Code?: LogCode; Limit?: number; }
225
- export type Status = "Healthy" | "Degraded" | "Outage";
226
- export type SessionState = "Loading" | "Ready" | "SessionEnded";
227
- /** The second GetState return is present only while the session is loading. */
228
- export type LoadPhase = "WaitingForErase" | "AcquiringSession" | "ReadingProfile" | "Retrying" | "Initializing" | "Importing" | "ImportThrottled";
229
- export type Visibility = "Replicated" | "ServerOnly" | "Shared";
230
- export type LifecycleReason = "load-failed" | "migration-failed" | "erasing" | "session-ended" | "player-left" | "shutdown" | "still-loading" | "timeout";
231
- export type RequestReason = "rate-limited" | "not-ready" | "unknown-command" | "bad-args" | "bad-idempotency-key" | "error" | "reply-encode-failed" | "timeout" | "send-failed" | "edit-mode" | "mock-error";
232
- declare const requestFailedBrand: unique symbol;
233
- /** Identity token returned only for framework refusals, never a handler result. */
234
- export interface RequestFailedMarker { readonly [requestFailedBrand]: true; }
235
- export type RequestFailure = LuaTuple<[false, RequestReason, RequestFailedMarker]>;
236
- export type ProductState = "purchasable" | "owned" | "paid-random-restricted" | "policy-pending" | "not-loaded";
237
- export type PurchaseReason = "player data not loaded" | "invalid Cost spec" | "invalid Cost amount" | "invalid cost path" | "cost path is not a spendable number" | "insufficient funds" | "paid random items are not available for this account" | "cannot check account settings right now; try again in a moment";
238
- export type GiftReason = "buyer data not loaded" | "invalid recipient" | "cannot gift yourself" | "gift cooldown" | "product retired" | "too many pending gifts" | "data services are experiencing issues; try again later" | "recipient already owns this" | "could not reserve gift credit; try again later" | "could not deliver gift; try again later" | "gift delivery could not be confirmed; do not send it again" | "a gift of this item is already pending; try again shortly" | "could not record gift intent; try again later" | "paid random items are not available for this account" | "cannot check account settings right now; try again in a moment";
239
- export type OperationResult = LuaTuple<[boolean, string | undefined]>;
240
-
241
- export interface SaveInfo { LastSaveAt?: number; LastResult?: "Ok" | "Fail"; Dirty: boolean; Size?: number; }
242
- export interface SaveEvent { Player: Player; Ok: boolean; Duration?: number; At: number; }
243
- export interface Anomaly { Player: Player; Path: Path; Value?: unknown; Reason: string; }
244
- export interface GiftReceived { FromUserId: number; Product: string; GiftId: string; }
245
- export interface VersionRecord { VersionId: string; CreatedAt: number; Size?: number; }
246
- export type ViolationKind = "WrongType" | "OutOfBounds" | "OverMaxLength" | "NotAMember" | "BadEncoding" | "UnknownKey";
247
- export interface SchemaViolation { Path: Path; Kind: ViolationKind; Detail: string; Advisory?: boolean; }
248
- export interface FlushOptions { Force?: boolean; Timeout?: number; }
249
- export interface UpdateOfflineOptions { Validate?: boolean; }
250
- export interface RestoreOptions { RollBackReserved?: boolean; }
251
- export interface CooldownOptions { IncludeOfflineTime?: boolean; }
252
- export interface MigrationContext {
253
- readonly AwaitBudget: (this: void, requestType: string, count?: number, timeout?: number) => LuaTuple<[boolean, Disconnect]>;
254
- }
255
-
256
- export type BigScore = Pick<BigValue, "M" | "E" | "Short" | "ToNumber" | "Log10">;
257
- export interface LeaderboardEntry { Rank: number; UserId: number; Name: string; Score: number | BigScore; }
258
- export type LeaderboardStatus = "Starting" | "Healthy" | "Degraded";
259
- /** Cached board health; reading it makes no DataStore requests. */
260
- export interface LeaderboardStatusInfo {
261
- Status: LeaderboardStatus;
262
- PendingWrites: number;
263
- RetryingWrites: number;
264
- RejectedWrites: number;
265
- LastReadAt?: number;
266
- ReadAge?: number;
267
- LastWriteAt?: number;
268
- LastReadError?: string;
269
- LastWriteError?: string;
270
- }
271
- /** A process-local bundle ID identifies the board's running bundle. */
272
- export interface LeaderboardSnapshotEntry extends LeaderboardStatusInfo { BundleId: number; Name: string; }
273
- export interface PassConfig { Id: number; Category?: string; }
274
- export interface PurchaseFilter { Kind?: "Robux" | "InGame"; Category?: string; ItemId?: string; Since?: number; Limit?: number; }
275
- /** RecordPurchase accepts game-defined fields, so only Kind is universally present. */
276
- export interface PurchaseEntry extends UnknownRecord {
277
- Kind: "Robux" | "InGame";
278
- Ts?: number;
279
- Category?: string;
280
- ItemId?: string;
281
- Product?: string;
282
- PurchaseId?: string;
283
- PriceInRobux?: number;
284
- Currency?: string;
285
- Amount?: number;
286
- Meta?: UnknownRecord;
287
- }
288
- export interface PurchaseLogOptions { RobuxCap?: number; InGameCap?: number; ReplicateRobux?: boolean; ReplicateInGame?: boolean; PurchaseLogCategories?: ReadonlyArray<string>; }
289
- export interface ProductInfo extends UnknownRecord {
290
- Name?: string;
291
- Description?: string;
292
- ProductId?: number;
293
- AssetId?: number;
294
- IconImageAssetId?: number;
295
- IsForSale?: boolean;
296
- PriceInRobux?: number;
297
- UserBasePriceInRobux?: number;
298
- PriceDiscountDetails?: UnknownRecord;
299
- }
300
- export interface PolicyInfo extends UnknownRecord { ArePaidRandomItemsRestricted?: boolean; }
301
- export interface ReceiptInfo {
302
- PlayerId: number;
303
- ProductId: number;
304
- PurchaseId: string;
305
- CurrencySpent?: number;
306
- PlaceIdWherePurchased?: number;
307
- }
308
-
309
- export interface EconomyMeta {
310
- Flow?: "Source" | "Sink";
311
- TransactionType?: Enum.AnalyticsEconomyTransactionType | string;
312
- ItemSku?: string;
313
- Currency?: string;
314
- Fields?: UnknownRecord;
315
- Source?: string;
316
- Item?: string;
317
- }
318
- export type EconomyFieldSpec = string | { Name: string; Prefix?: boolean };
319
- export interface EconomyCurrencyConfig { Label?: string; Fields?: ReadonlyArray<EconomyFieldSpec>; Resolve?: (this: void, player: Player) => UnknownRecord; }
320
- export type EconomyLogFn = (this: void, player: Player, flowType: Enum.AnalyticsEconomyFlowType, currencyType: string, amount: number, endingBalance: number, transactionType: string, itemSku?: string, customFields?: UnknownRecord) => void;
321
- export interface EconomyConfig { Resolve?: (this: void, player: Player) => UnknownRecord; Prefix?: boolean; Currencies?: { [currency: string]: EconomyCurrencyConfig }; LogEconomyEvent?: EconomyLogFn; }
322
-
323
- export interface ExchangeableSpec { Path: ReadonlyArray<string>; Kind: "Key" | "Qty" | "Stack"; Count?: string; Identity?: ReadonlyArray<string>; Ignore?: ReadonlyArray<string>; }
324
- export type ExchangeLeg =
325
- | { Path: Path; Kind: "Key"; Key: unknown; Amount?: never; Value?: unknown }
326
- | { Path: Path; Kind: "Qty"; Key?: never; Amount: number; Value?: unknown }
327
- | { Path: Path; Kind: "Stack"; Key: unknown; Amount: number; Value?: unknown };
328
- export interface OpenLeg { Path: Path; Kind: "Key" | "Qty" | "Stack"; Key?: unknown; Amount?: number; }
329
- export interface OpenExchange { Id: string; State: "Claimed" | "Staked" | "Delivering"; Partner?: number; Staked: OpenLeg[]; Owed: OpenLeg[]; Since?: number; }
330
- export interface ExchangeAPI {
331
- readonly Attempt: (this: void, playerA: Player, basketA: ReadonlyArray<ExchangeLeg>, playerB: Player, basketB: ReadonlyArray<ExchangeLeg>) => LuaTuple<["Committed" | "Aborted" | undefined, string | undefined]>;
332
- readonly Open: (this: void, player: Player) => OpenExchange[];
333
- readonly Discard: (this: void, exchangeId: string) => OperationResult;
334
- readonly Settle: (this: void, exchangeId: string, verdict: "Commit" | "Abort") => OperationResult;
335
- readonly Redirect: (this: void, exchangeId: string, userId: number, newKey: string) => OperationResult;
336
- }
337
-
338
- export interface BudgetSnapshot { Available: boolean; Reason?: string; Budgets: { [requestType: string]: number }; At: number; }
339
- export interface MetricObservation { Count: number; Average: number; Max: number; }
340
- export type Metrics = { [name: string]: number | MetricObservation };
341
- export interface Percentiles { P50: number; P90: number; P99: number; Samples: number; Age: number; Window: number; }
342
- export type PercentileSnapshot = { [name: string]: Percentiles };
343
- export interface AddonAction { Run: (this: void, args: unknown) => unknown; Writes?: boolean; }
344
- export type AddonActions = { [name: string]: AddonAction };
345
- export interface ConfigureOptions { AutoSaveInterval?: number; }
346
- export interface StatusThresholds { FailWindow?: number; FailCount?: number; RecoverStreak?: number; }
347
- export interface PeriodResetOptions { UtcOffset?: number; WeekStart?: "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"; }
348
-
349
- export interface MockState {
350
- Perks?: ReadonlyArray<string>;
351
- GiftCredits?: { [product: string]: number };
352
- PurchaseLogs?: { Robux?: ReadonlyArray<UnknownRecord>; InGame?: ReadonlyArray<UnknownRecord> };
353
- Leaderboards?: { [name: string]: ReadonlyArray<LeaderboardEntry> };
354
- }
355
-
1
+ import type { BigValue, Disconnect } from "./schema";
2
+
3
+ /** Arbitrary stored or external data is unknown until the caller validates it. */
4
+ export type UnknownRecord = { [key: string]: unknown };
5
+ export type PathSegment = string | number;
6
+ export type Path = ReadonlyArray<PathSegment>;
7
+ export type OpKind = "Init" | "Set" | "Insert" | "Remove" | "Clear";
8
+ export interface Op { Kind: OpKind; Path: Path; Value?: unknown; Index?: number; }
9
+
10
+ /** Transport functions are genuine colon methods; accessor/API functions are not. */
11
+ export interface ScribeTransport {
12
+ readonly Name: string;
13
+ readonly MaxFrameBytes?: number;
14
+ SendToClient(player: Player, bytes: buffer): void;
15
+ SendToAllClients?(bytes: buffer): void;
16
+ ListenServer(callback: (this: void, player: Player, bytes: buffer) => void): void;
17
+ SendToServer(bytes: buffer): void;
18
+ ListenClient(callback: (this: void, bytes: buffer) => void): void;
19
+ Release?(): void;
20
+ }
21
+
22
+ export interface Connection {
23
+ readonly Connected: boolean;
24
+ Disconnect(): void;
25
+ }
26
+ /** Read-only event surface. Scribe owns firing and destroying these signals. */
27
+ export interface Signal<Args extends unknown[]> {
28
+ Connect(callback: (this: void, ...args: Args) => void): Connection;
29
+ Once(callback: (this: void, ...args: Args) => void): Connection;
30
+ Wait(): LuaTuple<Args>;
31
+ }
32
+
33
+ export type LogLevel = "Debug" | "Info" | "Warn" | "Error" | "Fatal";
34
+ /** Each sink has its own severity filter and bounded callback queue. */
35
+ export interface LogSinkOptions { Level?: LogLevel; MaxQueued?: number; }
36
+ export type LogCategory = "Persistence" | "Replication" | "Transport" | "Commands" | "Leaderboards" | "Monetization" | "Gifting" | "Integrity" | "Lifecycle" | "Derived" | "Exchanges";
37
+ /** Public diagnostic codes, kept in sync with src/Types.luau. */
38
+ export type LogCode =
39
+ | "DATASTORE_CRITICAL"
40
+ | "DATASTORE_RECOVERED"
41
+ | "EXPORT_ENCODE_FAIL"
42
+ | "LEGACY_IMPORTED"
43
+ | "LEGACY_IMPORT_FAIL"
44
+ | "MIGRATED"
45
+ | "MESSAGE_SEND_FAIL"
46
+ | "MESSAGE_QUEUE_FULL"
47
+ | "MESSAGE_NO_LISTENER"
48
+ | "MESSAGE_HANDLER_ERROR"
49
+ | "MESSAGE_HANDLER_STALLED"
50
+ | "MIGRATION_FAIL"
51
+ | "MIGRATION_RECONCILE_DEPENDENT"
52
+ | "MIGRATION_RESERVED_DISCARDED"
53
+ | "MODE_OVERRIDES_LEGACY"
54
+ | "OFFLINE_READ_FAIL"
55
+ | "OFFLINE_WRITE_FAIL"
56
+ | "NOSAVE_WRITE_REFUSED"
57
+ | "PROFILE_ERASED"
58
+ | "PROFILE_ERASE_FAIL"
59
+ | "PROFILE_ERASE_PROGRESS_FAIL"
60
+ | "PROFILE_ERASE_RESUMED"
61
+ | "PROFILE_LOADED"
62
+ | "PROFILE_LOAD_FAIL"
63
+ | "PROFILE_RESET"
64
+ | "PROFILE_RESTORED"
65
+ | "PROFILE_RESTORE_FAIL"
66
+ | "RESTORE_RESERVED_PRESERVED"
67
+ | "PROFILE_SIZE"
68
+ | "SLOW_LOAD"
69
+ | "SLOW_IMPORT"
70
+ | "SAVE_WAIT_TIMEOUT"
71
+ | "PROFILE_STORE_ERROR"
72
+ | "PROFILE_STORE_SIGNAL_MISSING"
73
+ | "PROFILE_TOO_LARGE"
74
+ | "PROFILE_UNPERSISTABLE"
75
+ | "PROFILE_VERSION_AHEAD"
76
+ | "SAVE_INTERVAL_CLAMPED"
77
+ | "WIPE_GUARD_RATIO_CLAMPED"
78
+ | "HEALTH_THRESHOLDS_CONFLICT"
79
+ | "SAVE_INTERVAL_CONFLICT"
80
+ | "SAVE_INTERVAL_FAIL"
81
+ | "SAVE_INTERVAL_SET"
82
+ | "SHUTDOWN_DONE"
83
+ | "SHUTDOWN_FLUSH"
84
+ | "SIM_LOAD_FAILURE"
85
+ | "SIM_SESSION_STEAL"
86
+ | "STATUS_CHANGED"
87
+ | "UNKNOWN_ROOT_KEYS"
88
+ | "VERSION_QUERY_FAIL"
89
+ | "VERSION_READ_FAIL"
90
+ | "ANALYTICS_FAIL"
91
+ | "ANOMALY"
92
+ | "ECONOMY_FIELDS_OVERFLOW"
93
+ | "ECONOMY_FIELD_UNDECLARED"
94
+ | "PROFILE_OVERWRITTEN"
95
+ | "PROFILE_TOO_DEEP"
96
+ | "PROFILE_SCHEMA_VIOLATION"
97
+ | "TIMED_SWEEP_FAIL"
98
+ | "WIPE_GUARD_BLOCKED"
99
+ | "WIPE_GUARD_CLEARED"
100
+ | "WIPE_GUARD_FORCED"
101
+ | "WIPE_GUARD_TRIPPED"
102
+ | "CLIENT_HANDSHAKE_TIMEOUT"
103
+ | "FRAGMENT_REFUSED"
104
+ | "INIT_APPLIED"
105
+ | "INIT_SEND_FAIL"
106
+ | "MIRROR_RESYNC"
107
+ | "INIT_SENT"
108
+ | "INIT_UNDELIVERED"
109
+ | "OP_BEFORE_INIT"
110
+ | "OUTBOUND_OVERSIZE"
111
+ | "PROTOCOL_MISMATCH"
112
+ | "SCHEMA_MISMATCH"
113
+ | "SERIALIZE_FAIL"
114
+ | "SNAPSHOT_ROOT_DROPPED"
115
+ | "INBOUND_OVERSIZE"
116
+ | "INBOUND_OVERSIZE_LIMIT"
117
+ | "INBOUND_RATE_LIMITED"
118
+ | "INBOUND_WORK_LIMIT"
119
+ | "MALFORMED_FRAME"
120
+ | "MALFORMED_FRAME_LIMIT"
121
+ | "SEND_FAIL"
122
+ | "COMMAND_BAD_ARGS"
123
+ | "COMMAND_BAD_IDEMPOTENCY_KEY"
124
+ | "COMMAND_ERROR"
125
+ | "COMMAND_IDEM_EVICTED"
126
+ | "COMMAND_IDEM_SATURATED"
127
+ | "COMMAND_RATE_LIMITED"
128
+ | "COMMAND_REPLY_ENCODE_FAIL"
129
+ | "COMMAND_REPLY_TRUNCATED"
130
+ | "COMMAND_UNKNOWN"
131
+ | "SIM_COMMAND"
132
+ | "GRANT_FAIL"
133
+ | "GRANT_PARTIAL"
134
+ | "GRANT_SEEDED_ELEMENT"
135
+ | "RECEIPT_IN_FLIGHT"
136
+ | "RECEIPT_HISTORY_FULL"
137
+ | "OWNERSHIP_CHECK_FAIL"
138
+ | "PASS_PURCHASE_UNCONFIRMED"
139
+ | "PERK_GRANTED"
140
+ | "PERK_REVOKED"
141
+ | "PRODUCT_INFO_FAIL"
142
+ | "POLICY_READ_FAIL"
143
+ | "PAID_RANDOM_RECEIPT"
144
+ | "PRODUCT_INFO_THROTTLED"
145
+ | "PURCHASE_DUPLICATE"
146
+ | "PURCHASE_CLAIM_EVICTED"
147
+ | "PURCHASE_ID_EVICTED"
148
+ | "RECEIPT_DUPLICATE"
149
+ | "RECEIPT_GRANTED"
150
+ | "RECEIPT_HANDLER_BOUND"
151
+ | "RECEIPT_OFFLINE_RETRY"
152
+ | "RECEIPT_RETRY"
153
+ | "RECEIPT_UNKNOWN_PRODUCT"
154
+ | "SIM_RECEIPT"
155
+ | "UNDECLARED_CATEGORY"
156
+ | "UNDECLARED_PERK"
157
+ | "UNKNOWN_OWNS_KEY"
158
+ | "GIFT_AIM_CAP_REACHED"
159
+ | "GIFT_AIM_EXPIRED"
160
+ | "GIFT_AIM_SETTLED"
161
+ | "GIFT_CREDIT_ISSUED"
162
+ | "GIFT_CREDIT_REFUND_FAIL"
163
+ | "GIFT_CREDIT_UNCONFIRMED"
164
+ | "GIFT_CREDIT_UNKNOWN_PRODUCT"
165
+ | "GIFT_CREDIT_USED"
166
+ | "GIFT_DELIVERY_RETRY"
167
+ | "GIFT_INTENT_EXPIRED"
168
+ | "GIFT_INTENT_WRITE_FAIL"
169
+ | "GIFT_INVALID_RECIPIENT"
170
+ | "GIFT_NO_INTENT"
171
+ | "GIFT_RECEIPT_GRANTED"
172
+ | "GIFT_RECIPIENT_ALREADY_OWNS"
173
+ | "GIFT_UNKNOWN_PRODUCT"
174
+ | "RECEIPT_DECLINED_PENDING_CREDIT"
175
+ | "RECEIPT_HELD"
176
+ | "LB_ERASE_FAIL"
177
+ | "LB_INTERVAL_CLAMPED"
178
+ | "LB_QUEUE_OVERFLOW"
179
+ | "LB_READ_FAIL"
180
+ | "LB_SCORE_OUT_OF_RANGE"
181
+ | "LB_SHUTDOWN_FLUSH"
182
+ | "LB_STAT_RESOLVE_FAIL"
183
+ | "LB_UNKNOWN_BOARD"
184
+ | "LB_BUDGET_DEFERRED"
185
+ | "LB_WRITE_DROPPED"
186
+ | "LB_WRITE_FAIL"
187
+ | "SIM_LB_FLUSH"
188
+ | "EXCHANGE_INIT_TAMPER"
189
+ | "EXCHANGE_PARKED"
190
+ | "EXCHANGE_REGISTRATION_REFUSED"
191
+ | "EXCHANGE_RESET_REFUSED"
192
+ | "EXCHANGE_RESOLVED"
193
+ | "EXCHANGE_RESOLVE_ERROR"
194
+ | "EXCHANGE_STORE_UNAVAILABLE"
195
+ | "EXCHANGE_UNRESOLVED"
196
+ | "DERIVED_ERROR"
197
+ | "DERIVED_FEEDBACK"
198
+ | "DERIVED_MISMATCH"
199
+ | "API_NAME_COLLISION"
200
+ | "DEBUG_HOOK_ATTACHED"
201
+ | "DEBUG_HOOK_ATTRIBUTION"
202
+ | "DEBUG_HOOK_DUPLICATE"
203
+ | "DEBUG_HOOK_ERROR"
204
+ | "DEBUG_HOOK_FAIL"
205
+ | "DEBUG_HOOK_WRITES"
206
+ | "DEV_WARNING"
207
+ | "DYNAMIC_DEFAULT_FAILED"
208
+ | "LISTENER_ERROR"
209
+ | "ON_PLAYER_INIT_ERROR"
210
+ | "ON_PLAYER_INIT_LEDGER"
211
+ | "PLAYER_LEAVING_HOOK_SLOW"
212
+ | "SANDBOXED"
213
+ | "SERVER_STARTED"
214
+ | "SIM_STATUS"
215
+ | "SUBSYSTEM_HOOK_ERROR"
216
+ | "UNKNOWN_OPTION";
217
+ export interface LogEntry {
218
+ At: number;
219
+ Level: LogLevel;
220
+ Category: LogCategory;
221
+ Code: LogCode;
222
+ Message: string;
223
+ Context?: UnknownRecord;
224
+ }
225
+ export interface LogFilter { Level?: LogLevel; Category?: LogCategory; Code?: LogCode; Limit?: number; }
226
+ export type Status = "Healthy" | "Degraded" | "Outage";
227
+ export type SessionState = "Loading" | "Ready" | "SessionEnded";
228
+ /** The second GetState return is present only while the session is loading. */
229
+ export type LoadPhase = "WaitingForErase" | "AcquiringSession" | "ReadingProfile" | "Retrying" | "Initializing" | "Importing" | "ImportThrottled";
230
+ export type Visibility = "Replicated" | "ServerOnly" | "Shared";
231
+ export type LifecycleReason = "load-failed" | "migration-failed" | "erasing" | "session-ended" | "player-left" | "shutdown" | "still-loading" | "timeout";
232
+ export type RequestReason = "rate-limited" | "not-ready" | "unknown-command" | "bad-args" | "bad-idempotency-key" | "error" | "reply-encode-failed" | "timeout" | "send-failed" | "edit-mode" | "mock-error";
233
+ declare const requestFailedBrand: unique symbol;
234
+ /** Identity token returned only for framework refusals, never a handler result. */
235
+ export interface RequestFailedMarker { readonly [requestFailedBrand]: true; }
236
+ export type RequestFailure = LuaTuple<[false, RequestReason, RequestFailedMarker]>;
237
+ export type ProductState = "purchasable" | "owned" | "paid-random-restricted" | "policy-pending" | "not-loaded";
238
+ export type PurchaseReason = "player data not loaded" | "invalid Cost spec" | "invalid Cost amount" | "invalid cost path" | "cost path is not a spendable number" | "insufficient funds" | "paid random items are not available for this account" | "cannot check account settings right now; try again in a moment";
239
+ export type GiftReason = "buyer data not loaded" | "invalid recipient" | "cannot gift yourself" | "gift cooldown" | "product retired" | "too many pending gifts" | "data services are experiencing issues; try again later" | "recipient already owns this" | "could not reserve gift credit; try again later" | "could not deliver gift; try again later" | "gift delivery could not be confirmed; do not send it again" | "a gift of this item is already pending; try again shortly" | "could not record gift intent; try again later" | "paid random items are not available for this account" | "cannot check account settings right now; try again in a moment";
240
+ export type OperationResult = LuaTuple<[boolean, string | undefined]>;
241
+
242
+ export interface SaveInfo { LastSaveAt?: number; LastResult?: "Ok" | "Fail"; Dirty: boolean; Size?: number; }
243
+ export interface SaveEvent { Player: Player; Ok: boolean; Duration?: number; At: number; }
244
+ export interface Anomaly { Player: Player; Path: Path; Value?: unknown; Reason: string; }
245
+ export interface GiftReceived { FromUserId: number; Product: string; GiftId: string; }
246
+ export interface VersionRecord { VersionId: string; CreatedAt: number; Size?: number; }
247
+ export type ViolationKind = "WrongType" | "OutOfBounds" | "OverMaxLength" | "NotAMember" | "BadEncoding" | "UnknownKey";
248
+ export interface SchemaViolation { Path: Path; Kind: ViolationKind; Detail: string; Advisory?: boolean; }
249
+ export interface FlushOptions { Force?: boolean; Timeout?: number; }
250
+ export interface UpdateOfflineOptions { Validate?: boolean; }
251
+ export interface RestoreOptions { RollBackReserved?: boolean; }
252
+ export interface CooldownOptions { IncludeOfflineTime?: boolean; }
253
+ export interface MigrationContext {
254
+ readonly AwaitBudget: (this: void, requestType: string, count?: number, timeout?: number) => LuaTuple<[boolean, Disconnect]>;
255
+ }
256
+
257
+ export type BigScore = Pick<BigValue, "M" | "E" | "Short" | "ToNumber" | "Log10">;
258
+ export interface LeaderboardEntry { Rank: number; UserId: number; Name: string; Score: number | BigScore; }
259
+ export type LeaderboardStatus = "Starting" | "Healthy" | "Degraded";
260
+ /** Cached board health; reading it makes no DataStore requests. */
261
+ export interface LeaderboardStatusInfo {
262
+ Status: LeaderboardStatus;
263
+ PendingWrites: number;
264
+ RetryingWrites: number;
265
+ RejectedWrites: number;
266
+ LastReadAt?: number;
267
+ ReadAge?: number;
268
+ LastWriteAt?: number;
269
+ LastReadError?: string;
270
+ LastWriteError?: string;
271
+ }
272
+ /** A process-local bundle ID identifies the board's running bundle. */
273
+ export interface LeaderboardSnapshotEntry extends LeaderboardStatusInfo { BundleId: number; Name: string; }
274
+ export interface PassConfig { Id: number; Category?: string; }
275
+ export interface PurchaseFilter { Kind?: "Robux" | "InGame"; Category?: string; ItemId?: string; Since?: number; Limit?: number; }
276
+ /** RecordPurchase accepts game-defined fields, so only Kind is universally present. */
277
+ export interface PurchaseEntry extends UnknownRecord {
278
+ Kind: "Robux" | "InGame";
279
+ Ts?: number;
280
+ Category?: string;
281
+ ItemId?: string;
282
+ Product?: string;
283
+ PurchaseId?: string;
284
+ PriceInRobux?: number;
285
+ Currency?: string;
286
+ /** Big currencies use [mantissa, exponent]. */
287
+ Amount?: number | [number, number];
288
+ Meta?: UnknownRecord;
289
+ }
290
+ export interface PurchaseLogOptions { RobuxCap?: number; InGameCap?: number; ReplicateRobux?: boolean; ReplicateInGame?: boolean; PurchaseLogCategories?: ReadonlyArray<string>; }
291
+ export interface ProductInfo extends UnknownRecord {
292
+ Name?: string;
293
+ Description?: string;
294
+ ProductId?: number;
295
+ AssetId?: number;
296
+ IconImageAssetId?: number;
297
+ IsForSale?: boolean;
298
+ PriceInRobux?: number;
299
+ UserBasePriceInRobux?: number;
300
+ PriceDiscountDetails?: UnknownRecord;
301
+ }
302
+ export interface PolicyInfo extends UnknownRecord { ArePaidRandomItemsRestricted?: boolean; }
303
+ export interface ReceiptInfo {
304
+ PlayerId: number;
305
+ ProductId: number;
306
+ PurchaseId: string;
307
+ CurrencySpent?: number;
308
+ PlaceIdWherePurchased?: number;
309
+ }
310
+
311
+ export interface EconomyMeta {
312
+ Flow?: "Source" | "Sink";
313
+ TransactionType?: Enum.AnalyticsEconomyTransactionType | string;
314
+ ItemSku?: string;
315
+ Currency?: string;
316
+ Fields?: UnknownRecord;
317
+ Source?: string;
318
+ Item?: string;
319
+ }
320
+ export type EconomyFieldSpec = string | { Name: string; Prefix?: boolean };
321
+ export interface EconomyCurrencyConfig { Label?: string; Fields?: ReadonlyArray<EconomyFieldSpec>; Resolve?: (this: void, player: Player) => UnknownRecord; }
322
+ export type EconomyLogFn = (this: void, player: Player, flowType: Enum.AnalyticsEconomyFlowType, currencyType: string, amount: number, endingBalance: number, transactionType: string, itemSku?: string, customFields?: UnknownRecord) => void;
323
+ export interface EconomyConfig { Resolve?: (this: void, player: Player) => UnknownRecord; Prefix?: boolean; Currencies?: { [currency: string]: EconomyCurrencyConfig }; LogEconomyEvent?: EconomyLogFn; }
324
+
325
+ export interface ExchangeableSpec { Path: ReadonlyArray<string>; Kind: "Key" | "Qty" | "Stack"; Count?: string; Identity?: ReadonlyArray<string>; Ignore?: ReadonlyArray<string>; }
326
+ export type ExchangeLeg =
327
+ | { Path: Path; Kind: "Key"; Key: unknown; Amount?: never; Value?: unknown }
328
+ | { Path: Path; Kind: "Qty"; Key?: never; Amount: number; Value?: unknown }
329
+ | { Path: Path; Kind: "Stack"; Key: unknown; Amount: number; Value?: unknown };
330
+ export interface OpenLeg { Path: Path; Kind: "Key" | "Qty" | "Stack"; Key?: unknown; Amount?: number; }
331
+ export interface OpenExchange { Id: string; State: "Claimed" | "Staked" | "Delivering"; Partner?: number; Staked: OpenLeg[]; Owed: OpenLeg[]; Since?: number; }
332
+ export interface ExchangeAPI {
333
+ readonly Attempt: (this: void, playerA: Player, basketA: ReadonlyArray<ExchangeLeg>, playerB: Player, basketB: ReadonlyArray<ExchangeLeg>) => LuaTuple<["Committed" | "Aborted" | undefined, string | undefined]>;
334
+ readonly Open: (this: void, player: Player) => OpenExchange[];
335
+ readonly Discard: (this: void, exchangeId: string) => OperationResult;
336
+ readonly Settle: (this: void, exchangeId: string, verdict: "Commit" | "Abort") => OperationResult;
337
+ readonly Redirect: (this: void, exchangeId: string, userId: number, newKey: string) => OperationResult;
338
+ }
339
+
340
+ export interface BudgetSnapshot { Available: boolean; Reason?: string; Budgets: { [requestType: string]: number }; At: number; }
341
+ export interface MetricObservation { Count: number; Average: number; Max: number; }
342
+ export type Metrics = { [name: string]: number | MetricObservation };
343
+ export interface Percentiles { P50: number; P90: number; P99: number; Samples: number; Age: number; Window: number; }
344
+ export type PercentileSnapshot = { [name: string]: Percentiles };
345
+ export interface AddonAction { Run: (this: void, args: unknown) => unknown; Writes?: boolean; }
346
+ export type AddonActions = { [name: string]: AddonAction };
347
+ export interface ConfigureOptions { AutoSaveInterval?: number; }
348
+ export interface StatusThresholds { FailWindow?: number; FailCount?: number; RecoverStreak?: number; }
349
+ export interface PeriodResetOptions { UtcOffset?: number; WeekStart?: "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"; }
350
+
351
+ export interface MockState {
352
+ Perks?: ReadonlyArray<string>;
353
+ GiftCredits?: { [product: string]: number };
354
+ PurchaseLogs?: { Robux?: ReadonlyArray<UnknownRecord>; InGame?: ReadonlyArray<UnknownRecord> };
355
+ Leaderboards?: { [name: string]: ReadonlyArray<LeaderboardEntry> };
356
+ }
357
+