@rbxts/scribe 2.5.0 → 2.6.1

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/api.d.ts CHANGED
@@ -1,252 +1,334 @@
1
- import type { Accessor, PlayerData, ValueOf, InputOf, ClientSchema, SharedSchema, ReadonlyAccessor, NumericPaths, Disconnect, Datatype, BigValue } from "./schema";
2
- import type { UnknownRecord, ScribeTransport, Signal, LifecycleReason, SessionState, LoadPhase, Status, ProductState, RequestFailure, RequestFailedMarker, OperationResult, SaveInfo, SaveEvent, Anomaly, GiftReceived, VersionRecord, SchemaViolation, FlushOptions, UpdateOfflineOptions, RestoreOptions, CooldownOptions, MigrationContext, LeaderboardEntry, LeaderboardStatusInfo, PassConfig, PurchaseFilter, PurchaseEntry, PurchaseLogOptions, ProductInfo, PolicyInfo, ReceiptInfo, EconomyConfig, ExchangeableSpec, ExchangeAPI, LogLevel, StatusThresholds, PeriodResetOptions, MockState } from "./common";
3
-
4
- export interface LeaderboardConfig<T = unknown> {
5
- Stat: NumericPaths<T, true>;
6
- Limit?: number;
7
- Scale?: number;
8
- SigFigs?: number;
9
- Replicate?: boolean;
10
- RefreshInterval?: number;
11
- /** Minimum seconds between changed-score writes per player/store (default 30, minimum 1). Ignored for Server scope. */
12
- WriteInterval?: number;
13
- StoreName?: string;
14
- Period?: "Daily" | "Weekly";
15
- Mode?: "Gain" | "Peak";
16
- Scope?: "Global" | "Server";
17
- }
18
- export interface ProductConfig<T = unknown> {
19
- Id: number;
20
- Category?: string;
21
- Grant?: (this: void, data: PlayerData<T>) => void;
22
- Grants?: string;
23
- PaidRandom?: boolean;
24
- }
25
- export interface PurchaseSpec<T = unknown> {
26
- Cost: { Path: NumericPaths<T, false>; Amount: number };
27
- Category?: string;
28
- ItemId: string;
29
- Grant?: (this: void, data: PlayerData<T>) => void;
30
- Meta?: UnknownRecord;
31
- IdempotencyKey?: string;
32
- PaidRandom?: boolean;
33
- }
34
-
35
- /** A shared command contract maps each command name to its arguments and LuaTuple result. */
36
- export type CommandArguments<F> = F extends (this: void, ...args: infer A) => unknown ? A : never;
37
- export type CommandReturn<F> = F extends (this: void, ...args: never[]) => infer R ? R extends LuaTuple<unknown[]> ? R : never : never;
38
- export type CommandHandler<F> = (this: void, player: Player, ...args: CommandArguments<F>) => CommandReturn<F>;
39
- export interface CommandSpec { Args?: ReadonlyArray<unknown>; Idempotent?: boolean; }
40
-
41
- /** Uncontracted commands deliberately expose unknown results instead of claiming inferred safety. */
42
- export type RequestFunction<C> = keyof C extends never
43
- ? (this: void, name: string, ...args: unknown[]) => LuaTuple<unknown[]>
44
- : <K extends keyof C & string>(this: void, name: K, ...args: CommandArguments<C[K]>) => CommandReturn<C[K]> | RequestFailure;
45
- export type RequestOnceFunction<C> = keyof C extends never
46
- ? (this: void, name: string, key: string, ...args: unknown[]) => LuaTuple<unknown[]>
47
- : <K extends keyof C & string>(this: void, name: K, key: string, ...args: CommandArguments<C[K]>) => CommandReturn<C[K]> | RequestFailure;
48
- export type RegisterCommand<C> = keyof C extends never ? {
49
- <A extends unknown[], R>(this: void, name: string, handler: (this: void, player: Player, ...args: A) => R): void;
50
- <A extends unknown[], R>(this: void, name: string, spec: CommandSpec, handler: (this: void, player: Player, ...args: A) => R): void;
51
- } : {
52
- <K extends keyof C & string>(this: void, name: K, handler: CommandHandler<C[K]>): void;
53
- <K extends keyof C & string>(this: void, name: K, spec: CommandSpec, handler: CommandHandler<C[K]>): void;
54
- };
55
- export type MockCommand<C> = keyof C extends never
56
- ? <A extends unknown[], R>(this: void, name: string, handler: (this: void, ...args: A) => R) => void
57
- : <K extends keyof C & string>(this: void, name: K, handler: C[K]) => void;
58
-
59
- export type ServerStore<S> = { readonly [K in keyof S]: Accessor<S[K]> };
60
- export type ClientServerStore<S> = { readonly [K in keyof ClientSchema<S>]: ReadonlyAccessor<ClientSchema<S>[K]> };
61
- type ServerStoreMember<S> = keyof S extends never ? { readonly ServerStore?: never } : { readonly ServerStore: ServerStore<S> };
62
- type ClientStoreMember<S> = keyof S extends never ? { readonly ServerStore?: never } : { readonly ServerStore: ClientServerStore<S> };
63
- export type SharedData<T> = ValueOf<SharedSchema<ClientSchema<T>>>;
64
-
65
- export interface ServerAPI<T, C = {}> {
66
- readonly Get: (this: void, player: Player) => PlayerData<T>;
67
- readonly WaitForData: (this: void, player: Player, timeout?: number) => LuaTuple<[PlayerData<T> | undefined, LifecycleReason | undefined]>;
68
- readonly GetState: (this: void, player: Player) => LuaTuple<[SessionState, LoadPhase | undefined]>;
69
- readonly Batch: (this: void, player: Player, callback: (this: void) => void) => void;
70
- readonly Transaction: (this: void, player: Player, callback: (this: void) => void) => OperationResult;
71
- readonly Flush: (this: void, player: Player, options?: FlushOptions) => boolean;
72
- readonly GetSaveInfo: (this: void, player: Player) => SaveInfo;
73
- /** Offline/history reads are packed, potentially old schemas, not live accessor values. */
74
- readonly GetOffline: (this: void, userId: number) => UnknownRecord | undefined;
75
- readonly UpdateOffline: (this: void, userId: number, callback: (this: void, rawData: UnknownRecord) => void, options?: UpdateOfflineOptions) => LuaTuple<[boolean, string | undefined, SchemaViolation[] | undefined]>;
76
- readonly ListVersions: (this: void, userId: number, limit?: number) => VersionRecord[];
77
- readonly GetVersion: (this: void, userId: number, versionId: string) => UnknownRecord | undefined;
78
- readonly RestoreVersion: (this: void, userId: number, versionId: string, options?: RestoreOptions) => OperationResult;
79
- readonly Erase: (this: void, userId: number) => OperationResult;
80
- readonly Export: (this: void, userId: number) => string | undefined;
81
- readonly Command: RegisterCommand<C>;
82
- readonly GetLeaderboard: (this: void, name: string, limit?: number, offset?: number) => LeaderboardEntry[];
83
- readonly GetMyRank: (this: void, player: Player, name: string) => number | undefined;
84
- readonly GetLeaderboardRefreshIn: (this: void, name: string) => number | undefined;
85
- readonly GetLeaderboardStatus: (this: void, name: string) => LeaderboardStatusInfo | undefined;
86
- readonly GetLeaderboardResetIn: (this: void, name: string) => number | undefined;
87
- readonly PromptPurchase: (this: void, player: Player, name: string) => OperationResult;
88
- readonly GetProductState: (this: void, player: Player, name: string) => ProductState;
89
- readonly PromptGift: (this: void, buyer: Player, productName: string, recipientUserId: number) => OperationResult;
90
- readonly GetGiftCredits: (this: void, player: Player) => { [product: string]: number };
91
- readonly HandleReceipt: (this: void, receipt: ReceiptInfo) => Enum.ProductPurchaseDecision;
92
- readonly TryHandleReceipt: (this: void, receipt: ReceiptInfo) => Enum.ProductPurchaseDecision | undefined;
93
- readonly Owns: (this: void, player: Player, key: string) => boolean;
94
- readonly OwnsAsync: (this: void, player: Player, key: string, timeout?: number) => boolean;
95
- readonly ObserveOwned: (this: void, player: Player, key: string, callback: (this: void, owned: boolean) => void) => Disconnect;
96
- readonly GrantPerk: (this: void, player: Player, key: string) => void;
97
- readonly RevokePerk: (this: void, player: Player, key: string) => void;
98
- readonly Purchase: (this: void, player: Player, spec: PurchaseSpec<T>) => OperationResult;
99
- readonly RecordPurchase: (this: void, player: Player, entry: UnknownRecord) => void;
100
- readonly GetPurchases: (this: void, player: Player, filter?: PurchaseFilter) => PurchaseEntry[];
101
- readonly OnCooldown: (this: void, player: Player, key: string, seconds: number, options?: CooldownOptions) => LuaTuple<[boolean, number]>;
102
- readonly PeekCooldown: (this: void, player: Player, key: string) => LuaTuple<[boolean, number]>;
103
- readonly ClearCooldown: (this: void, player: Player, key: string) => void;
104
- readonly SendMessage: (this: void, userId: number, message: unknown) => boolean;
105
- readonly Exchange: ExchangeAPI;
106
- readonly OnSave: Signal<[SaveEvent]>;
107
- readonly SessionEnded: Signal<[Player, LifecycleReason]>;
108
- readonly OnAnomaly: Signal<[Anomaly]>;
109
- readonly OnGiftReceived: Signal<[Player, GiftReceived]>;
110
- readonly OnGiftCredit: Signal<[Player, string]>;
111
- readonly OnOwnershipChanged: Signal<[Player, string, boolean]>;
112
- readonly OnCooldownEnded: Signal<[Player, string]>;
113
- readonly OnLeaderboard: Signal<[string, LeaderboardEntry[]]>;
114
- readonly OnMessage: Signal<[Player, unknown]>;
115
- /** External ProfileStore implementation; narrow to its own public package type before use. */
116
- readonly ProfileStore: unknown;
117
- /** Escape hatch requiring explicit validation/assertion at its boundary. */
118
- readonly Raw: unknown;
119
- readonly Stop: (this: void) => void;
120
- }
121
- export type ServerData<T, S = {}, C = {}> = ServerAPI<T, C> & ServerStoreMember<S>;
122
-
123
- /** Partial records for Mock; arrays and Roblox engine datatypes remain whole values. */
124
- export type MockValues<T> = T extends Datatype | buffer | BigValue | ReadonlyArray<unknown> | ReadonlyMap<unknown, unknown> ? T : T extends object ? { [K in keyof T]?: MockValues<T[K]> } : T;
125
- export interface ClientAPI<T, C = {}> {
126
- readonly IsReady: (this: void) => boolean;
127
- readonly WaitForData: (this: void, timeout?: number) => boolean;
128
- readonly Batch: (this: void, callback: (this: void) => void) => void;
129
- readonly Request: RequestFunction<C>;
130
- readonly RequestOnce: RequestOnceFunction<C>;
131
- readonly GetLeaderboard: (this: void, name: string, limit?: number) => LeaderboardEntry[];
132
- readonly GetMyRank: (this: void, name: string) => number | undefined;
133
- readonly OnLeaderboard: Signal<[string, LeaderboardEntry[]]>;
134
- readonly GetServiceStatus: (this: void) => Status;
135
- readonly OnServiceStatus: Signal<[Status]>;
136
- readonly GetShared: (this: void, playerOrUserId: Player | number) => SharedData<T> | undefined;
137
- readonly OnSharedChanged: Signal<[number, SharedData<T> | undefined]>;
138
- readonly Owns: (this: void, key: string) => boolean;
139
- readonly OwnsAsync: (this: void, key: string, timeout?: number) => boolean;
140
- readonly ObserveOwned: (this: void, key: string, callback: (this: void, owned: boolean) => void) => Disconnect;
141
- readonly OnOwnershipChanged: Signal<[string, boolean]>;
142
- readonly GetProductInfo: (this: void, name: string) => ProductInfo | undefined;
143
- readonly GetPrice: (this: void, name: string) => number | undefined;
144
- readonly GetProductInfoAsync: (this: void, name: string, timeout?: number) => ProductInfo | undefined;
145
- readonly GetPriceAsync: (this: void, name: string, timeout?: number) => number | undefined;
146
- readonly ObserveProductInfo: (this: void, name: string, callback: (this: void, info: ProductInfo | undefined) => void) => Disconnect;
147
- readonly PrefetchProductInfo: (this: void, names?: ReadonlyArray<string>) => void;
148
- readonly RefreshProductInfo: (this: void, name?: string) => void;
149
- /** Asks the server to validate and prompt for the local player. Success is not a completed purchase; a timeout may occur after the prompt opens. No automatic retry. */
150
- readonly PromptPurchase: (this: void, name: string) => LuaTuple<[boolean, string | undefined, RequestFailedMarker | undefined]>;
151
- readonly GetProductState: (this: void, name: string) => ProductState;
152
- readonly ObserveProductState: (this: void, name: string, callback: (this: void, state: ProductState) => void) => Disconnect;
153
- readonly GetSaveInfo: (this: void) => SaveInfo;
154
- readonly GetGiftCredits: (this: void) => { [product: string]: number };
155
- readonly GetPurchases: (this: void, filter?: PurchaseFilter) => PurchaseEntry[];
156
- readonly Mock: (this: void, values?: MockValues<InputOf<ClientSchema<T>>>, state?: MockState) => void;
157
- readonly MockCommand: MockCommand<C>;
158
- readonly Raw: unknown;
159
- readonly Stop: (this: void) => void;
160
- }
161
- /** Client field writes are local optimistic edits; server-owned roots remain read-only. */
162
- export type ClientData<T, S = {}, C = {}> = Omit<PlayerData<ClientSchema<T>>, Extract<keyof PlayerData<ClientSchema<T>>, keyof ClientAPI<T, C> | "ServerStore">> & ClientAPI<T, C> & ClientStoreMember<S>;
163
- export interface Bundle<T, S = {}, C = {}> { readonly Server: ServerData<T, S, C>; readonly Client: ClientData<T, S, C>; }
164
-
165
- /** Both templates share root field IDs. Broad dictionaries are validated at runtime. */
166
- type DisjointStoreRoots<T, S> = string extends keyof T | keyof S ? unknown : { [K in keyof T & keyof S]?: never };
167
- export interface ScribeOptions<T, S = {}, C = {}> {
168
- Template: T;
169
- ServerStore?: S & DisjointStoreRoots<NoInfer<T>, NoInfer<S>>;
170
- Transport?: ScribeTransport | "Default";
171
- Migrations?: { [version: number]: (this: void, data: UnknownRecord) => void };
172
- UserOwnsGamePassAsync?: (this: void, userId: number, passId: number) => boolean;
173
- GetProductInfoAsync?: (this: void, assetId: number, infoType: Enum.InfoType) => ProductInfo | undefined;
174
- GetPolicyInfoAsync?: (this: void, player: Player) => PolicyInfo | undefined;
175
- DevMode?: boolean;
176
- IsRunning?: boolean;
177
- MigrationShadow?: boolean;
178
- ImportLegacyData?: (this: void, player: Player, userId: number, migration: MigrationContext) => UnknownRecord | undefined;
179
- MigrationConcurrency?: number;
180
- OnPlayerInit?: (this: void, player: Player, rawData: UnknownRecord, isNewProfile: boolean, migration: MigrationContext) => void;
181
- OnPlayerLeaving?: (this: void, player: Player, data: PlayerData<T>, reason: LifecycleReason) => void;
182
- ProfileStoreIndex: string;
183
- ProfileKeyPrefix: string;
184
- SaveInterval?: number;
185
- /** A supplied ProfileStore module/module script is an external integration boundary. */
186
- ProfileStore?: unknown;
187
- Mode?: "Live" | "Mock" | "NoSave";
188
- TargetUserId?: number;
189
- UseMock?: boolean;
190
- ViewedUserId?: number;
191
- OverriddenUserId?: number;
192
- DontSave?: boolean;
193
- ResetData?: boolean;
194
- LoadFailurePolicy?: "Kick" | "Wait";
195
- LoadTimeout?: number;
196
- EraseJoinTimeout?: number;
197
- VersionAheadPolicy?: "Kick" | "Allow";
198
- KickOnSessionEnd?: boolean;
199
- LoadFailureMessage?: string;
200
- LegacyImportFailureMessage?: string;
201
- MigrationFailureMessage?: string;
202
- VersionAheadMessage?: string;
203
- SchemaFailureMessage?: string;
204
- RateLimitedMessage?: string;
205
- ErasingMessage?: string;
206
- SessionEndMessage?: string;
207
- SessionStolenMessage?: string;
208
- SessionInterruptedMessage?: string;
209
- Leaderboards?: { [name: string]: LeaderboardConfig<T> };
210
- PeriodReset?: PeriodResetOptions;
211
- Products?: { [name: string]: ProductConfig<T> };
212
- /** Historical products still settle receipts and existing gifts, without offering new sales. */
213
- RetiredProducts?: { [name: string]: ProductConfig<T> };
214
- Passes?: { [name: string]: PassConfig };
215
- Perks?: ReadonlyArray<string>;
216
- OwnReceipts?: boolean;
217
- Exchangeable?: { [name: string]: ExchangeableSpec };
218
- PurchaseLog?: PurchaseLogOptions;
219
- GiftCooldown?: number;
220
- GiftMaxPending?: number;
221
- GiftIntentTTL?: number;
222
- /** Legacy default for purchase-claim and gift-aim retention; receipt history remains fixed at 30 days. */
223
- PurchaseIdTTL?: number;
224
- /** @deprecated Ignored. Completed receipt IDs are no longer evicted to meet a count cap. */
225
- MaxProcessedPurchaseIds?: number;
226
- /** Receipt-history admission budget, from 1 to 2097152 bytes (default 1048576). */
227
- MaxReceiptHistoryBytes?: number;
228
- PurchaseClaimTTL?: number;
229
- MaxPurchaseClaims?: number;
230
- AllowDuplicateGifts?: boolean;
231
- NoGiftIntentPolicy?: "GrantOrCredit" | "Hold";
232
- Economy?: EconomyConfig;
233
- CommandRateLimit?: number;
234
- RequestTimeout?: number;
235
- MaxInboundBytes?: number;
236
- MaxInboundRetainedBytes?: number;
237
- MaxOutboundBytes?: number;
238
- MaxInboundFrameRate?: number;
239
- TransportChannel?: string;
240
- BoundsPolicy?: "Clamp" | "Reject";
241
- WipeGuardPolicy?: "Warn" | "Block";
242
- SchemaPolicy?: "Warn" | "Reject";
243
- BudgetPolicy?: "Defer";
244
- WipeGuardShrinkRatio?: number;
245
- LogLevel?: LogLevel;
246
- /** Severity retained by GetRecentLogs, independently of console and sink filters. */
247
- LogRingLevel?: LogLevel;
248
- LogRingSize?: number;
249
- StatusThresholds?: StatusThresholds;
250
- Banner?: boolean;
251
- StudioHook?: boolean;
252
- }
1
+ import type { Accessor, PlayerData, ValueOf, InputOf, ClientSchema, SharedSchema, ReadonlyAccessor, NumericPaths, Disconnect, Datatype, BigValue, BigOperand } from "./schema";
2
+ import type { UnknownRecord, ScribeTransport, Signal, LifecycleReason, SessionState, LoadPhase, Status, ProductState, RequestFailure, RequestFailedMarker, OperationResult, SaveInfo, SaveEvent, Anomaly, GiftReceived, VersionRecord, SchemaViolation, FlushOptions, UpdateOfflineOptions, RestoreOptions, CooldownOptions, MigrationContext, LeaderboardEntry, LeaderboardStatusInfo, PassConfig, PurchaseFilter, PurchaseEntry, PurchaseLogOptions, ProductInfo, PolicyInfo, ReceiptInfo, EconomyConfig, ExchangeableSpec, ExchangeAPI, LogLevel, StatusThresholds, PeriodResetOptions, MockState } from "./common";
3
+
4
+ export interface LeaderboardConfig<T = unknown> {
5
+ Stat: NumericPaths<T, true>;
6
+ Limit?: number;
7
+ Scale?: number;
8
+ SigFigs?: number;
9
+ Replicate?: boolean;
10
+ RefreshInterval?: number;
11
+ /** Minimum seconds between changed-score writes per player/store (default 30, minimum 1). Ignored for Server scope. */
12
+ WriteInterval?: number;
13
+ StoreName?: string;
14
+ Period?: "Daily" | "Weekly";
15
+ Mode?: "Gain" | "Peak";
16
+ Scope?: "Global" | "Server";
17
+ }
18
+ export interface ProductConfig<T = unknown> {
19
+ Id: number;
20
+ Category?: string;
21
+ Grant?: (this: void, data: PlayerData<T>) => void;
22
+ Grants?: string;
23
+ PaidRandom?: boolean;
24
+ }
25
+ export interface PurchaseSpec<T = unknown> {
26
+ /** Strings and BigValue amounts require a Big currency. */
27
+ Cost: { Path: NumericPaths<T, true>; Amount: BigOperand };
28
+ Category?: string;
29
+ ItemId: string;
30
+ Grant?: (this: void, data: PlayerData<T>) => void;
31
+ Meta?: UnknownRecord;
32
+ IdempotencyKey?: string;
33
+ PaidRandom?: boolean;
34
+ }
35
+
36
+ /** A shared command contract maps each command name to its arguments and LuaTuple result. */
37
+ export type CommandArguments<F> = F extends (this: void, ...args: infer A) => unknown ? A : never;
38
+ export type CommandReturn<F> = F extends (this: void, ...args: never[]) => infer R ? R extends LuaTuple<unknown[]> ? R : never : never;
39
+ export type CommandHandler<F> = (this: void, player: Player, ...args: CommandArguments<F>) => CommandReturn<F>;
40
+ export interface CommandSpec { Args?: ReadonlyArray<unknown>; Idempotent?: boolean; }
41
+
42
+ /** Uncontracted commands deliberately expose unknown results instead of claiming inferred safety. */
43
+ export type RequestFunction<C> = keyof C extends never
44
+ ? (this: void, name: string, ...args: unknown[]) => LuaTuple<unknown[]>
45
+ : <K extends keyof C & string>(this: void, name: K, ...args: CommandArguments<C[K]>) => CommandReturn<C[K]> | RequestFailure;
46
+ export type RequestOnceFunction<C> = keyof C extends never
47
+ ? (this: void, name: string, key: string, ...args: unknown[]) => LuaTuple<unknown[]>
48
+ : <K extends keyof C & string>(this: void, name: K, key: string, ...args: CommandArguments<C[K]>) => CommandReturn<C[K]> | RequestFailure;
49
+ export type RegisterCommand<C> = keyof C extends never ? {
50
+ <A extends unknown[], R>(this: void, name: string, handler: (this: void, player: Player, ...args: A) => R): void;
51
+ <A extends unknown[], R>(this: void, name: string, spec: CommandSpec, handler: (this: void, player: Player, ...args: A) => R): void;
52
+ } : {
53
+ <K extends keyof C & string>(this: void, name: K, handler: CommandHandler<C[K]>): void;
54
+ <K extends keyof C & string>(this: void, name: K, spec: CommandSpec, handler: CommandHandler<C[K]>): void;
55
+ };
56
+ export type MockCommand<C> = keyof C extends never
57
+ ? <A extends unknown[], R>(this: void, name: string, handler: (this: void, ...args: A) => R) => void
58
+ : <K extends keyof C & string>(this: void, name: K, handler: C[K]) => void;
59
+
60
+ export type ServerStore<S> = { readonly [K in keyof S]: Accessor<S[K]> };
61
+ export type ClientServerStore<S> = { readonly [K in keyof ClientSchema<S>]: ReadonlyAccessor<ClientSchema<S>[K]> };
62
+ type ServerStoreMember<S> = keyof S extends never ? { readonly ServerStore?: never } : { readonly ServerStore: ServerStore<S> };
63
+ type ClientStoreMember<S> = keyof S extends never ? { readonly ServerStore?: never } : { readonly ServerStore: ClientServerStore<S> };
64
+ export type SharedData<T> = ValueOf<SharedSchema<ClientSchema<T>>>;
65
+
66
+ export interface ServerAPI<T, C = {}> {
67
+ /** Returns the player's accessor tree; errors unless the profile is Ready. */
68
+ readonly Get: (this: void, player: Player) => PlayerData<T>;
69
+ /** Waits for a Ready profile, returning `undefined` and a reason on failure. */
70
+ readonly WaitForData: (this: void, player: Player, timeout?: number) => LuaTuple<[PlayerData<T> | undefined, LifecycleReason | undefined]>;
71
+ /** Reads session state and loading phase without yielding. */
72
+ readonly GetState: (this: void, player: Player) => LuaTuple<[SessionState, LoadPhase | undefined]>;
73
+ /** Groups writes into one replication flush and container notification pass. */
74
+ readonly Batch: (this: void, player: Player, callback: (this: void) => void) => void;
75
+ /** Runs non-yielding writes atomically in memory; does not save them. */
76
+ readonly Transaction: (this: void, player: Player, callback: (this: void) => void) => OperationResult;
77
+ /** Waits for pending changes to save; requires a Ready profile. */
78
+ readonly Flush: (this: void, player: Player, options?: FlushOptions) => boolean;
79
+ /** Reads the player's last save result and pending-change state. */
80
+ readonly GetSaveInfo: (this: void, player: Player) => SaveInfo;
81
+ /** Returns a raw profile snapshot; packed values may use an older schema. */
82
+ readonly GetOffline: (this: void, userId: number) => UnknownRecord | undefined;
83
+ /** Updates an offline profile, with optional template validation. */
84
+ readonly UpdateOffline: (this: void, userId: number, callback: (this: void, rawData: UnknownRecord) => void, options?: UpdateOfflineOptions) => LuaTuple<[boolean, string | undefined, SchemaViolation[] | undefined]>;
85
+ /** Lists saved profile versions for support tools. */
86
+ readonly ListVersions: (this: void, userId: number, limit?: number) => VersionRecord[];
87
+ /** Reads a historical raw snapshot, which may use an older schema. */
88
+ readonly GetVersion: (this: void, userId: number, versionId: string) => UnknownRecord | undefined;
89
+ /** Restores an existing offline profile while preserving reserved data by default. */
90
+ readonly RestoreVersion: (this: void, userId: number, versionId: string, options?: RestoreOptions) => OperationResult;
91
+ /** Deletes the profile and leaderboard records while blocking this user's joins. */
92
+ readonly Erase: (this: void, userId: number) => OperationResult;
93
+ /** Serializes a profile to JSON, or returns `undefined` when absent. */
94
+ readonly Export: (this: void, userId: number) => string | undefined;
95
+ /** Registers a validated, rate-limited command for Ready players. */
96
+ readonly Command: RegisterCommand<C>;
97
+ /** Reads cached board results without a live DataStore request. */
98
+ readonly GetLeaderboard: (this: void, name: string, limit?: number, offset?: number) => LeaderboardEntry[];
99
+ /** Reads the player's rank from the leaderboard cache. */
100
+ readonly GetMyRank: (this: void, player: Player, name: string) => number | undefined;
101
+ /** Reads the next scheduled refresh delay; `undefined` until scheduled. */
102
+ readonly GetLeaderboardRefreshIn: (this: void, name: string) => number | undefined;
103
+ /** Reads board health without a DataStore request. */
104
+ readonly GetLeaderboardStatus: (this: void, name: string) => LeaderboardStatusInfo | undefined;
105
+ /** Reads the time remaining in a periodic board's current period. */
106
+ readonly GetLeaderboardResetIn: (this: void, name: string) => number | undefined;
107
+ /** Opens a validated product or pass prompt; success does not mean the purchase completed. */
108
+ readonly PromptPurchase: (this: void, player: Player, name: string) => OperationResult;
109
+ /** Reads the ownership and policy state used by purchase prompts. */
110
+ readonly GetProductState: (this: void, player: Player, name: string) => ProductState;
111
+ /** Gifts a product perk using a credit or a paid prompt with a saved recipient. */
112
+ readonly PromptGift: (this: void, buyer: Player, productName: string, recipientUserId: number) => OperationResult;
113
+ /** Reads the player's unassigned gift credits. */
114
+ readonly GetGiftCredits: (this: void, player: Player) => { [product: string]: number };
115
+ /** Processes a Scribe receipt with persisted deduplication. */
116
+ readonly HandleReceipt: (this: void, receipt: ReceiptInfo) => Enum.ProductPurchaseDecision;
117
+ /** Processes known products and returns `undefined` for another receipt handler. */
118
+ readonly TryHandleReceipt: (this: void, receipt: ReceiptInfo) => Enum.ProductPurchaseDecision | undefined;
119
+ /** Reads cached pass, perk, or Roblox Plus ownership without yielding. */
120
+ readonly Owns: (this: void, player: Player, key: string) => boolean;
121
+ /** Verifies uncached pass ownership with Roblox before returning. */
122
+ readonly OwnsAsync: (this: void, player: Player, key: string, timeout?: number) => boolean;
123
+ /** Reports ownership now and on changes; returns a disconnect function. */
124
+ readonly ObserveOwned: (this: void, player: Player, key: string, callback: (this: void, owned: boolean) => void) => Disconnect;
125
+ /** Grants a perk through Scribe's ownership state. */
126
+ readonly GrantPerk: (this: void, player: Player, key: string) => void;
127
+ /** Removes a granted perk from Scribe's ownership state. */
128
+ readonly RevokePerk: (this: void, player: Player, key: string) => void;
129
+ /** Debits, grants, and logs atomically; failures roll back the purchase. */
130
+ readonly Purchase: (this: void, player: Player, spec: PurchaseSpec<T>) => OperationResult;
131
+ /** Adds a game-defined entry to the in-game purchase log. */
132
+ readonly RecordPurchase: (this: void, player: Player, entry: UnknownRecord) => void;
133
+ /** Reads filtered purchase history, newest first. */
134
+ readonly GetPurchases: (this: void, player: Player, filter?: PurchaseFilter) => PurchaseEntry[];
135
+ /** Starts an inactive cooldown; returns its previous state and seconds left. */
136
+ readonly OnCooldown: (this: void, player: Player, key: string, seconds: number, options?: CooldownOptions) => LuaTuple<[boolean, number]>;
137
+ /** Reads cooldown state without starting or extending it. */
138
+ readonly PeekCooldown: (this: void, player: Player, key: string) => LuaTuple<[boolean, number]>;
139
+ /** Clears a stored cooldown. */
140
+ readonly ClearCooldown: (this: void, player: Player, key: string) => void;
141
+ /** Queues a durable message; receiving handlers must tolerate repeats. */
142
+ readonly SendMessage: (this: void, userId: number, message: unknown) => boolean;
143
+ /** Trades declared value between players and recovers unfinished exchanges. */
144
+ readonly Exchange: ExchangeAPI;
145
+ /** Fires after each save attempt, including failures. */
146
+ readonly OnSave: Signal<[SaveEvent]>;
147
+ /** Fires when a player's session ends. */
148
+ readonly SessionEnded: Signal<[Player, LifecycleReason]>;
149
+ /** Fires when data validation or integrity checks detect an anomaly. */
150
+ readonly OnAnomaly: Signal<[Anomaly]>;
151
+ /** Fires when a player receives a gift. */
152
+ readonly OnGiftReceived: Signal<[Player, GiftReceived]>;
153
+ /** Fires when a player receives an unassigned gift credit. */
154
+ readonly OnGiftCredit: Signal<[Player, string]>;
155
+ /** Fires when effective ownership changes after load. */
156
+ readonly OnOwnershipChanged: Signal<[Player, string, boolean]>;
157
+ /** Fires when a cooldown expires during an active session. */
158
+ readonly OnCooldownEnded: Signal<[Player, string]>;
159
+ /** Fires when cached board contents change. */
160
+ readonly OnLeaderboard: Signal<[string, LeaderboardEntry[]]>;
161
+ /** Delivers durable messages; handlers must be idempotent. */
162
+ readonly OnMessage: Signal<[Player, unknown]>;
163
+ /** External ProfileStore implementation; narrow to its own public package type before use. */
164
+ readonly ProfileStore: unknown;
165
+ /** Escape hatch requiring explicit validation/assertion at its boundary. */
166
+ readonly Raw: unknown;
167
+ /** Stops this bundle's workers and releases its listeners. */
168
+ readonly Stop: (this: void) => void;
169
+ }
170
+ export type ServerData<T, S = {}, C = {}> = ServerAPI<T, C> & ServerStoreMember<S>;
171
+
172
+ /** Partial records for Mock; arrays and Roblox engine datatypes remain whole values. */
173
+ export type MockValues<T> = T extends Datatype | buffer | BigValue | ReadonlyArray<unknown> | ReadonlyMap<unknown, unknown> ? T : T extends object ? { [K in keyof T]?: MockValues<T[K]> } : T;
174
+ export interface ClientAPI<T, C = {}> {
175
+ /** Reads snapshot readiness without yielding. */
176
+ readonly IsReady: (this: void) => boolean;
177
+ /** Waits for the first snapshot, returning false on timeout. */
178
+ readonly WaitForData: (this: void, timeout?: number) => boolean;
179
+ /** Coalesces local container notifications; writes stay on this client. */
180
+ readonly Batch: (this: void, callback: (this: void) => void) => void;
181
+ /** Sends a command to the server and waits for its reply. */
182
+ readonly Request: RequestFunction<C>;
183
+ /** Sends a keyed command so retries reuse a retained server result. */
184
+ readonly RequestOnce: RequestOnceFunction<C>;
185
+ /** Reads the replicated leaderboard cache without requesting a refresh. */
186
+ readonly GetLeaderboard: (this: void, name: string, limit?: number) => LeaderboardEntry[];
187
+ /** Finds the local player's rank in the replicated board. */
188
+ readonly GetMyRank: (this: void, name: string) => number | undefined;
189
+ /** Fires when a replicated leaderboard changes. */
190
+ readonly OnLeaderboard: Signal<[string, LeaderboardEntry[]]>;
191
+ /** Reads the replicated data-service health. */
192
+ readonly GetServiceStatus: (this: void) => Status;
193
+ /** Fires when the replicated service health changes. */
194
+ readonly OnServiceStatus: Signal<[Status]>;
195
+ /** Reads another player's replicated Shared roots. */
196
+ readonly GetShared: (this: void, playerOrUserId: Player | number) => SharedData<T> | undefined;
197
+ /** Fires when another player's Shared roots change or are removed. */
198
+ readonly OnSharedChanged: Signal<[number, SharedData<T> | undefined]>;
199
+ /** Reads mirrored ownership after the profile loads. */
200
+ readonly Owns: (this: void, key: string) => boolean;
201
+ /** Waits for the server's initial ownership sync before reading the mirror. */
202
+ readonly OwnsAsync: (this: void, key: string, timeout?: number) => boolean;
203
+ /** Reports ownership now and on changes; returns a disconnect function. */
204
+ readonly ObserveOwned: (this: void, key: string, callback: (this: void, owned: boolean) => void) => Disconnect;
205
+ /** Fires for ownership changes after the initial baseline. */
206
+ readonly OnOwnershipChanged: Signal<[string, boolean]>;
207
+ /** Reads cached player-specific marketplace info, fetching on demand. */
208
+ readonly GetProductInfo: (this: void, name: string) => ProductInfo | undefined;
209
+ /** Reads the local player's cached Robux price, or `undefined` while loading. */
210
+ readonly GetPrice: (this: void, name: string) => number | undefined;
211
+ /** Waits for marketplace info, returning `undefined` on timeout or failure. */
212
+ readonly GetProductInfoAsync: (this: void, name: string, timeout?: number) => ProductInfo | undefined;
213
+ /** Waits for the local player's Robux price. */
214
+ readonly GetPriceAsync: (this: void, name: string, timeout?: number) => number | undefined;
215
+ /** Reports cached product info and updates; returns a disconnect function. */
216
+ readonly ObserveProductInfo: (this: void, name: string, callback: (this: void, info: ProductInfo | undefined) => void) => Disconnect;
217
+ /** Warms selected product info in one batch. */
218
+ readonly PrefetchProductInfo: (this: void, names?: ReadonlyArray<string>) => void;
219
+ /** Invalidates cached marketplace info and starts fresh reads. */
220
+ readonly RefreshProductInfo: (this: void, name?: string) => void;
221
+ /** Asks the server to validate and prompt for the local player. Success is not a completed purchase; a timeout may occur after the prompt opens. No automatic retry. */
222
+ readonly PromptPurchase: (this: void, name: string) => LuaTuple<[boolean, string | undefined, RequestFailedMarker | undefined]>;
223
+ /** Reads the mirrored ownership and policy state for shop UI. */
224
+ readonly GetProductState: (this: void, name: string) => ProductState;
225
+ /** Reports shop state now and on changes; returns a disconnect function. */
226
+ readonly ObserveProductState: (this: void, name: string, callback: (this: void, state: ProductState) => void) => Disconnect;
227
+ /** Reads the owner's replicated save status. */
228
+ readonly GetSaveInfo: (this: void) => SaveInfo;
229
+ /** Reads unassigned gift credits from the local mirror. */
230
+ readonly GetGiftCredits: (this: void) => { [product: string]: number };
231
+ /** Reads purchase history only when its replication is enabled. */
232
+ readonly GetPurchases: (this: void, filter?: PurchaseFilter) => PurchaseEntry[];
233
+ /** Seeds local mirror data in edit mode only. */
234
+ readonly Mock: (this: void, values?: MockValues<InputOf<ClientSchema<T>>>, state?: MockState) => void;
235
+ /** Registers an edit-mode command handler without a server. */
236
+ readonly MockCommand: MockCommand<C>;
237
+ /** Exposes the raw API; validate or assert its type before use. */
238
+ readonly Raw: unknown;
239
+ /** Releases this bundle's listeners, retry loop, and mirror. */
240
+ readonly Stop: (this: void) => void;
241
+ }
242
+ type ClientTree<T> = Accessor<ClientSchema<T>, true, false, false, false, true>;
243
+ /** Client writes are local; server-owned roots and timer deadlines are read-only. */
244
+ export type ClientData<T, S = {}, C = {}> = Omit<ClientTree<T>, Extract<keyof ClientTree<T>, keyof ClientAPI<T, C> | "ServerStore">> & ClientAPI<T, C> & ClientStoreMember<S>;
245
+ export interface Bundle<T, S = {}, C = {}> { readonly Server: ServerData<T, S, C>; readonly Client: ClientData<T, S, C>; }
246
+
247
+ /** Both templates share root field IDs. Broad dictionaries are validated at runtime. */
248
+ type DisjointStoreRoots<T, S> = string extends keyof T | keyof S ? unknown : { [K in keyof T & keyof S]?: never };
249
+ export interface ScribeOptions<T, S = {}, C = {}> {
250
+ Template: T;
251
+ ServerStore?: S & DisjointStoreRoots<NoInfer<T>, NoInfer<S>>;
252
+ Transport?: ScribeTransport | "Default";
253
+ Migrations?: { [version: number]: (this: void, data: UnknownRecord) => void };
254
+ UserOwnsGamePassAsync?: (this: void, userId: number, passId: number) => boolean;
255
+ GetProductInfoAsync?: (this: void, assetId: number, infoType: Enum.InfoType) => ProductInfo | undefined;
256
+ GetPolicyInfoAsync?: (this: void, player: Player) => PolicyInfo | undefined;
257
+ DevMode?: boolean;
258
+ IsRunning?: boolean;
259
+ MigrationShadow?: boolean;
260
+ ImportLegacyData?: (this: void, player: Player, userId: number, migration: MigrationContext) => UnknownRecord | undefined;
261
+ MigrationConcurrency?: number;
262
+ OnPlayerInit?: (this: void, player: Player, rawData: UnknownRecord, isNewProfile: boolean, migration: MigrationContext) => void;
263
+ OnPlayerLeaving?: (this: void, player: Player, data: PlayerData<T>, reason: LifecycleReason) => void;
264
+ ProfileStoreIndex: string;
265
+ ProfileKeyPrefix: string;
266
+ SaveInterval?: number;
267
+ /** A supplied ProfileStore module/module script is an external integration boundary. */
268
+ ProfileStore?: unknown;
269
+ Mode?: "Live" | "Mock" | "NoSave";
270
+ TargetUserId?: number;
271
+ UseMock?: boolean;
272
+ ViewedUserId?: number;
273
+ OverriddenUserId?: number;
274
+ DontSave?: boolean;
275
+ ResetData?: boolean;
276
+ LoadFailurePolicy?: "Kick" | "Wait";
277
+ LoadTimeout?: number;
278
+ EraseJoinTimeout?: number;
279
+ VersionAheadPolicy?: "Kick" | "Allow";
280
+ KickOnSessionEnd?: boolean;
281
+ LoadFailureMessage?: string;
282
+ LegacyImportFailureMessage?: string;
283
+ MigrationFailureMessage?: string;
284
+ VersionAheadMessage?: string;
285
+ SchemaFailureMessage?: string;
286
+ RateLimitedMessage?: string;
287
+ ErasingMessage?: string;
288
+ SessionEndMessage?: string;
289
+ SessionStolenMessage?: string;
290
+ SessionInterruptedMessage?: string;
291
+ Leaderboards?: { [name: string]: LeaderboardConfig<T> };
292
+ PeriodReset?: PeriodResetOptions;
293
+ Products?: { [name: string]: ProductConfig<T> };
294
+ /** Historical products still settle receipts and existing gifts, without offering new sales. */
295
+ RetiredProducts?: { [name: string]: ProductConfig<T> };
296
+ Passes?: { [name: string]: PassConfig };
297
+ Perks?: ReadonlyArray<string>;
298
+ OwnReceipts?: boolean;
299
+ Exchangeable?: { [name: string]: ExchangeableSpec };
300
+ PurchaseLog?: PurchaseLogOptions;
301
+ GiftCooldown?: number;
302
+ GiftMaxPending?: number;
303
+ GiftIntentTTL?: number;
304
+ /** Legacy default for purchase-claim and gift-aim retention; receipt history remains fixed at 30 days. */
305
+ PurchaseIdTTL?: number;
306
+ /** @deprecated Ignored. Completed receipt IDs are no longer evicted to meet a count cap. */
307
+ MaxProcessedPurchaseIds?: number;
308
+ /** Receipt-history admission budget, from 1 to 2097152 bytes (default 1048576). */
309
+ MaxReceiptHistoryBytes?: number;
310
+ PurchaseClaimTTL?: number;
311
+ MaxPurchaseClaims?: number;
312
+ AllowDuplicateGifts?: boolean;
313
+ NoGiftIntentPolicy?: "GrantOrCredit" | "Hold";
314
+ Economy?: EconomyConfig;
315
+ CommandRateLimit?: number;
316
+ RequestTimeout?: number;
317
+ MaxInboundBytes?: number;
318
+ MaxInboundRetainedBytes?: number;
319
+ MaxOutboundBytes?: number;
320
+ MaxInboundFrameRate?: number;
321
+ TransportChannel?: string;
322
+ BoundsPolicy?: "Clamp" | "Reject";
323
+ WipeGuardPolicy?: "Warn" | "Block";
324
+ SchemaPolicy?: "Warn" | "Reject";
325
+ BudgetPolicy?: "Defer";
326
+ WipeGuardShrinkRatio?: number;
327
+ LogLevel?: LogLevel;
328
+ /** Severity retained by GetRecentLogs, independently of console and sink filters. */
329
+ LogRingLevel?: LogLevel;
330
+ LogRingSize?: number;
331
+ StatusThresholds?: StatusThresholds;
332
+ Banner?: boolean;
333
+ StudioHook?: boolean;
334
+ }