@rbxts/scribe 2.6.0 → 2.7.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/README.md +1 -1
- package/Scribe-source-map.json +1 -1
- package/package.json +1 -1
- package/src/Client/init.luau +41 -7
- package/src/Internal/Big.luau +11 -3
- package/src/Internal/Datatypes.luau +12 -6
- package/src/Internal/Signal.luau +21 -0
- package/src/Internal/Template.luau +18 -0
- package/src/Internal/Version.luau +1 -1
- package/src/Server/Commands.luau +17 -3
- package/src/Server/Monetization.luau +5 -4
- package/src/Server/Persistence.luau +35 -2
- package/src/Server/Replication.luau +110 -70
- package/src/Server/Timed.luau +7 -1
- package/src/Types.luau +31 -3
- package/src/init.luau +501 -127
- package/types/api.d.ts +89 -6
- package/types/common.d.ts +23 -2
- package/types/index.d.ts +58 -3
- package/types/schema.d.ts +87 -23
package/types/api.d.ts
CHANGED
|
@@ -18,7 +18,8 @@ export interface LeaderboardConfig<T = unknown> {
|
|
|
18
18
|
export interface ProductConfig<T = unknown> {
|
|
19
19
|
Id: number;
|
|
20
20
|
Category?: string;
|
|
21
|
-
|
|
21
|
+
/** Runs on the buyer's data, or the recipient's for gifts. */
|
|
22
|
+
Grant?: (this: void, data: PlayerData<T>, player: Player) => void;
|
|
22
23
|
Grants?: string;
|
|
23
24
|
PaidRandom?: boolean;
|
|
24
25
|
}
|
|
@@ -27,7 +28,8 @@ export interface PurchaseSpec<T = unknown> {
|
|
|
27
28
|
Cost: { Path: NumericPaths<T, true>; Amount: BigOperand };
|
|
28
29
|
Category?: string;
|
|
29
30
|
ItemId: string;
|
|
30
|
-
|
|
31
|
+
/** Runs on the buyer's data. */
|
|
32
|
+
Grant?: (this: void, data: PlayerData<T>, player: Player) => void;
|
|
31
33
|
Meta?: UnknownRecord;
|
|
32
34
|
IdempotencyKey?: string;
|
|
33
35
|
PaidRandom?: boolean;
|
|
@@ -64,103 +66,184 @@ type ClientStoreMember<S> = keyof S extends never ? { readonly ServerStore?: nev
|
|
|
64
66
|
export type SharedData<T> = ValueOf<SharedSchema<ClientSchema<T>>>;
|
|
65
67
|
|
|
66
68
|
export interface ServerAPI<T, C = {}> {
|
|
69
|
+
/** Returns the player's accessor tree; errors unless the profile is Ready. */
|
|
67
70
|
readonly Get: (this: void, player: Player) => PlayerData<T>;
|
|
71
|
+
/** Waits for a Ready profile, returning `undefined` and a reason on failure. */
|
|
68
72
|
readonly WaitForData: (this: void, player: Player, timeout?: number) => LuaTuple<[PlayerData<T> | undefined, LifecycleReason | undefined]>;
|
|
73
|
+
/** Reads session state and loading phase without yielding. */
|
|
69
74
|
readonly GetState: (this: void, player: Player) => LuaTuple<[SessionState, LoadPhase | undefined]>;
|
|
75
|
+
/** Groups writes into one replication flush and container notification pass. */
|
|
70
76
|
readonly Batch: (this: void, player: Player, callback: (this: void) => void) => void;
|
|
77
|
+
/** Runs non-yielding writes atomically in memory; does not save them. */
|
|
71
78
|
readonly Transaction: (this: void, player: Player, callback: (this: void) => void) => OperationResult;
|
|
79
|
+
/** Waits for pending changes to save; requires a Ready profile. */
|
|
72
80
|
readonly Flush: (this: void, player: Player, options?: FlushOptions) => boolean;
|
|
81
|
+
/** Reads the player's last save result and pending-change state. */
|
|
73
82
|
readonly GetSaveInfo: (this: void, player: Player) => SaveInfo;
|
|
74
|
-
/**
|
|
83
|
+
/** Returns a raw profile snapshot; packed values may use an older schema. */
|
|
75
84
|
readonly GetOffline: (this: void, userId: number) => UnknownRecord | undefined;
|
|
85
|
+
/** Updates an offline profile, with optional template validation. */
|
|
76
86
|
readonly UpdateOffline: (this: void, userId: number, callback: (this: void, rawData: UnknownRecord) => void, options?: UpdateOfflineOptions) => LuaTuple<[boolean, string | undefined, SchemaViolation[] | undefined]>;
|
|
87
|
+
/** Lists saved profile versions for support tools. */
|
|
77
88
|
readonly ListVersions: (this: void, userId: number, limit?: number) => VersionRecord[];
|
|
89
|
+
/** Reads a historical raw snapshot, which may use an older schema. */
|
|
78
90
|
readonly GetVersion: (this: void, userId: number, versionId: string) => UnknownRecord | undefined;
|
|
91
|
+
/** Restores an existing offline profile while preserving reserved data by default. */
|
|
79
92
|
readonly RestoreVersion: (this: void, userId: number, versionId: string, options?: RestoreOptions) => OperationResult;
|
|
93
|
+
/** Deletes the profile and leaderboard records while blocking this user's joins. */
|
|
80
94
|
readonly Erase: (this: void, userId: number) => OperationResult;
|
|
95
|
+
/** Serializes a profile to JSON, or returns `undefined` when absent. */
|
|
81
96
|
readonly Export: (this: void, userId: number) => string | undefined;
|
|
97
|
+
/** Registers a validated, rate-limited command for Ready players. */
|
|
82
98
|
readonly Command: RegisterCommand<C>;
|
|
99
|
+
/** Reads cached board results without a live DataStore request. */
|
|
83
100
|
readonly GetLeaderboard: (this: void, name: string, limit?: number, offset?: number) => LeaderboardEntry[];
|
|
101
|
+
/** Reads the player's rank from the leaderboard cache. */
|
|
84
102
|
readonly GetMyRank: (this: void, player: Player, name: string) => number | undefined;
|
|
103
|
+
/** Reads the next scheduled refresh delay; `undefined` until scheduled. */
|
|
85
104
|
readonly GetLeaderboardRefreshIn: (this: void, name: string) => number | undefined;
|
|
105
|
+
/** Reads board health without a DataStore request. */
|
|
86
106
|
readonly GetLeaderboardStatus: (this: void, name: string) => LeaderboardStatusInfo | undefined;
|
|
107
|
+
/** Reads the time remaining in a periodic board's current period. */
|
|
87
108
|
readonly GetLeaderboardResetIn: (this: void, name: string) => number | undefined;
|
|
109
|
+
/** Opens a validated product or pass prompt; success does not mean the purchase completed. */
|
|
88
110
|
readonly PromptPurchase: (this: void, player: Player, name: string) => OperationResult;
|
|
111
|
+
/** Reads the ownership and policy state used by purchase prompts. */
|
|
89
112
|
readonly GetProductState: (this: void, player: Player, name: string) => ProductState;
|
|
113
|
+
/** Gifts a product perk using a credit or a paid prompt with a saved recipient. */
|
|
90
114
|
readonly PromptGift: (this: void, buyer: Player, productName: string, recipientUserId: number) => OperationResult;
|
|
115
|
+
/** Reads the player's unassigned gift credits. */
|
|
91
116
|
readonly GetGiftCredits: (this: void, player: Player) => { [product: string]: number };
|
|
117
|
+
/** Processes a Scribe receipt with persisted deduplication. */
|
|
92
118
|
readonly HandleReceipt: (this: void, receipt: ReceiptInfo) => Enum.ProductPurchaseDecision;
|
|
119
|
+
/** Processes known products and returns `undefined` for another receipt handler. */
|
|
93
120
|
readonly TryHandleReceipt: (this: void, receipt: ReceiptInfo) => Enum.ProductPurchaseDecision | undefined;
|
|
121
|
+
/** Reads cached pass, perk, or Roblox Plus ownership without yielding. */
|
|
94
122
|
readonly Owns: (this: void, player: Player, key: string) => boolean;
|
|
123
|
+
/** Verifies uncached pass ownership with Roblox before returning. */
|
|
95
124
|
readonly OwnsAsync: (this: void, player: Player, key: string, timeout?: number) => boolean;
|
|
125
|
+
/** Reports ownership now and on changes; returns a disconnect function. */
|
|
96
126
|
readonly ObserveOwned: (this: void, player: Player, key: string, callback: (this: void, owned: boolean) => void) => Disconnect;
|
|
127
|
+
/** Grants a perk through Scribe's ownership state. */
|
|
97
128
|
readonly GrantPerk: (this: void, player: Player, key: string) => void;
|
|
129
|
+
/** Removes a granted perk from Scribe's ownership state. */
|
|
98
130
|
readonly RevokePerk: (this: void, player: Player, key: string) => void;
|
|
131
|
+
/** Debits, grants, and logs atomically; failures roll back the purchase. */
|
|
99
132
|
readonly Purchase: (this: void, player: Player, spec: PurchaseSpec<T>) => OperationResult;
|
|
133
|
+
/** Adds a game-defined entry to the in-game purchase log. */
|
|
100
134
|
readonly RecordPurchase: (this: void, player: Player, entry: UnknownRecord) => void;
|
|
135
|
+
/** Reads filtered purchase history, newest first. */
|
|
101
136
|
readonly GetPurchases: (this: void, player: Player, filter?: PurchaseFilter) => PurchaseEntry[];
|
|
137
|
+
/** Starts an inactive cooldown; returns its previous state and seconds left. */
|
|
102
138
|
readonly OnCooldown: (this: void, player: Player, key: string, seconds: number, options?: CooldownOptions) => LuaTuple<[boolean, number]>;
|
|
139
|
+
/** Reads cooldown state without starting or extending it. */
|
|
103
140
|
readonly PeekCooldown: (this: void, player: Player, key: string) => LuaTuple<[boolean, number]>;
|
|
141
|
+
/** Clears a stored cooldown. */
|
|
104
142
|
readonly ClearCooldown: (this: void, player: Player, key: string) => void;
|
|
143
|
+
/** Queues a durable message; receiving handlers must tolerate repeats. */
|
|
105
144
|
readonly SendMessage: (this: void, userId: number, message: unknown) => boolean;
|
|
145
|
+
/** Trades declared value between players and recovers unfinished exchanges. */
|
|
106
146
|
readonly Exchange: ExchangeAPI;
|
|
147
|
+
/** Fires after each save attempt, including failures. */
|
|
107
148
|
readonly OnSave: Signal<[SaveEvent]>;
|
|
149
|
+
/** Fires when a player's session ends. */
|
|
108
150
|
readonly SessionEnded: Signal<[Player, LifecycleReason]>;
|
|
151
|
+
/** Fires when data validation or integrity checks detect an anomaly. */
|
|
109
152
|
readonly OnAnomaly: Signal<[Anomaly]>;
|
|
153
|
+
/** Fires when a player receives a gift. */
|
|
110
154
|
readonly OnGiftReceived: Signal<[Player, GiftReceived]>;
|
|
155
|
+
/** Fires when a player receives an unassigned gift credit. */
|
|
111
156
|
readonly OnGiftCredit: Signal<[Player, string]>;
|
|
157
|
+
/** Fires when effective ownership changes after load. */
|
|
112
158
|
readonly OnOwnershipChanged: Signal<[Player, string, boolean]>;
|
|
159
|
+
/** Fires when a cooldown expires during an active session. */
|
|
113
160
|
readonly OnCooldownEnded: Signal<[Player, string]>;
|
|
161
|
+
/** Fires when cached board contents change. */
|
|
114
162
|
readonly OnLeaderboard: Signal<[string, LeaderboardEntry[]]>;
|
|
163
|
+
/** Delivers durable messages; handlers must be idempotent. */
|
|
115
164
|
readonly OnMessage: Signal<[Player, unknown]>;
|
|
116
165
|
/** External ProfileStore implementation; narrow to its own public package type before use. */
|
|
117
166
|
readonly ProfileStore: unknown;
|
|
118
167
|
/** Escape hatch requiring explicit validation/assertion at its boundary. */
|
|
119
168
|
readonly Raw: unknown;
|
|
169
|
+
/** Stops this bundle's workers and releases its listeners. */
|
|
120
170
|
readonly Stop: (this: void) => void;
|
|
121
171
|
}
|
|
122
172
|
export type ServerData<T, S = {}, C = {}> = ServerAPI<T, C> & ServerStoreMember<S>;
|
|
123
173
|
|
|
124
|
-
/**
|
|
174
|
+
/** Mock merges records, dictionaries and maps by key. Arrays, sets, Flags and engine datatypes replace whole values. */
|
|
125
175
|
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;
|
|
126
176
|
export interface ClientAPI<T, C = {}> {
|
|
177
|
+
/** Reads snapshot readiness without yielding. */
|
|
127
178
|
readonly IsReady: (this: void) => boolean;
|
|
179
|
+
/** Waits for the first snapshot, returning false on timeout. */
|
|
128
180
|
readonly WaitForData: (this: void, timeout?: number) => boolean;
|
|
181
|
+
/** Coalesces local container notifications; writes stay on this client. */
|
|
129
182
|
readonly Batch: (this: void, callback: (this: void) => void) => void;
|
|
183
|
+
/** Sends a command to the server and waits for its reply. */
|
|
130
184
|
readonly Request: RequestFunction<C>;
|
|
185
|
+
/** Sends a keyed command so retries reuse a retained server result. */
|
|
131
186
|
readonly RequestOnce: RequestOnceFunction<C>;
|
|
187
|
+
/** Reads the replicated leaderboard cache without requesting a refresh. */
|
|
132
188
|
readonly GetLeaderboard: (this: void, name: string, limit?: number) => LeaderboardEntry[];
|
|
189
|
+
/** Finds the local player's rank in the replicated board. */
|
|
133
190
|
readonly GetMyRank: (this: void, name: string) => number | undefined;
|
|
191
|
+
/** Fires when a replicated leaderboard changes. */
|
|
134
192
|
readonly OnLeaderboard: Signal<[string, LeaderboardEntry[]]>;
|
|
193
|
+
/** Reads the replicated data-service health. */
|
|
135
194
|
readonly GetServiceStatus: (this: void) => Status;
|
|
195
|
+
/** Fires when the replicated service health changes. */
|
|
136
196
|
readonly OnServiceStatus: Signal<[Status]>;
|
|
197
|
+
/** Reads another player's replicated Shared roots. */
|
|
137
198
|
readonly GetShared: (this: void, playerOrUserId: Player | number) => SharedData<T> | undefined;
|
|
199
|
+
/** Fires when another player's Shared roots change or are removed. */
|
|
138
200
|
readonly OnSharedChanged: Signal<[number, SharedData<T> | undefined]>;
|
|
201
|
+
/** Reads mirrored ownership after the profile loads. */
|
|
139
202
|
readonly Owns: (this: void, key: string) => boolean;
|
|
203
|
+
/** Waits for the server's initial ownership sync before reading the mirror. */
|
|
140
204
|
readonly OwnsAsync: (this: void, key: string, timeout?: number) => boolean;
|
|
205
|
+
/** Returns a disconnect immediately. Reports current ownership once loaded and on changes. */
|
|
141
206
|
readonly ObserveOwned: (this: void, key: string, callback: (this: void, owned: boolean) => void) => Disconnect;
|
|
207
|
+
/** Fires for ownership changes after the initial baseline. */
|
|
142
208
|
readonly OnOwnershipChanged: Signal<[string, boolean]>;
|
|
209
|
+
/** Reads cached player-specific marketplace info, fetching on demand. */
|
|
143
210
|
readonly GetProductInfo: (this: void, name: string) => ProductInfo | undefined;
|
|
211
|
+
/** Reads the local player's cached Robux price, or `undefined` while loading. */
|
|
144
212
|
readonly GetPrice: (this: void, name: string) => number | undefined;
|
|
213
|
+
/** Waits for marketplace info, returning `undefined` on timeout or failure. */
|
|
145
214
|
readonly GetProductInfoAsync: (this: void, name: string, timeout?: number) => ProductInfo | undefined;
|
|
215
|
+
/** Waits for the local player's Robux price. */
|
|
146
216
|
readonly GetPriceAsync: (this: void, name: string, timeout?: number) => number | undefined;
|
|
217
|
+
/** Reports cached product info and updates; returns a disconnect function. */
|
|
147
218
|
readonly ObserveProductInfo: (this: void, name: string, callback: (this: void, info: ProductInfo | undefined) => void) => Disconnect;
|
|
219
|
+
/** Warms selected product info in one batch. */
|
|
148
220
|
readonly PrefetchProductInfo: (this: void, names?: ReadonlyArray<string>) => void;
|
|
221
|
+
/** Invalidates cached marketplace info and starts fresh reads. */
|
|
149
222
|
readonly RefreshProductInfo: (this: void, name?: string) => void;
|
|
150
223
|
/** 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. */
|
|
151
224
|
readonly PromptPurchase: (this: void, name: string) => LuaTuple<[boolean, string | undefined, RequestFailedMarker | undefined]>;
|
|
225
|
+
/** Reads the mirrored ownership and policy state for shop UI. */
|
|
152
226
|
readonly GetProductState: (this: void, name: string) => ProductState;
|
|
227
|
+
/** Reports shop state now and on changes; returns a disconnect function. */
|
|
153
228
|
readonly ObserveProductState: (this: void, name: string, callback: (this: void, state: ProductState) => void) => Disconnect;
|
|
229
|
+
/** Waits for load, then reads the owner's replicated save status. */
|
|
154
230
|
readonly GetSaveInfo: (this: void) => SaveInfo;
|
|
231
|
+
/** Waits for load, then reads unassigned gift credits. */
|
|
155
232
|
readonly GetGiftCredits: (this: void) => { [product: string]: number };
|
|
233
|
+
/** Waits for load, then reads the enabled purchase logs. */
|
|
156
234
|
readonly GetPurchases: (this: void, filter?: PurchaseFilter) => PurchaseEntry[];
|
|
235
|
+
/** Seeds local mirror data in edit mode only. */
|
|
157
236
|
readonly Mock: (this: void, values?: MockValues<InputOf<ClientSchema<T>>>, state?: MockState) => void;
|
|
237
|
+
/** Registers an edit-mode command handler without a server. */
|
|
158
238
|
readonly MockCommand: MockCommand<C>;
|
|
239
|
+
/** Exposes the raw API; validate or assert its type before use. */
|
|
159
240
|
readonly Raw: unknown;
|
|
241
|
+
/** Releases this bundle's listeners, retry loop, and mirror. */
|
|
160
242
|
readonly Stop: (this: void) => void;
|
|
161
243
|
}
|
|
162
|
-
|
|
163
|
-
|
|
244
|
+
type ClientTree<T> = Accessor<ClientSchema<T>, true, false, false, false, true>;
|
|
245
|
+
/** Client writes are local; server-owned roots and timer deadlines are read-only. */
|
|
246
|
+
export type ClientData<T, S = {}, C = {}> = Omit<ClientTree<T>, Extract<keyof ClientTree<T>, keyof ClientAPI<T, C> | "ServerStore">> & ClientAPI<T, C> & ClientStoreMember<S>;
|
|
164
247
|
export interface Bundle<T, S = {}, C = {}> { readonly Server: ServerData<T, S, C>; readonly Client: ClientData<T, S, C>; }
|
|
165
248
|
|
|
166
249
|
/** Both templates share root field IDs. Broad dictionaries are validated at runtime. */
|
package/types/common.d.ts
CHANGED
|
@@ -11,22 +11,32 @@ export interface Op { Kind: OpKind; Path: Path; Value?: unknown; Index?: number;
|
|
|
11
11
|
export interface ScribeTransport {
|
|
12
12
|
readonly Name: string;
|
|
13
13
|
readonly MaxFrameBytes?: number;
|
|
14
|
+
/** Sends an encoded frame to one client. */
|
|
14
15
|
SendToClient(player: Player, bytes: buffer): void;
|
|
16
|
+
/** Sends an encoded frame to every client. */
|
|
15
17
|
SendToAllClients?(bytes: buffer): void;
|
|
18
|
+
/** Registers the server callback for incoming client frames. */
|
|
16
19
|
ListenServer(callback: (this: void, player: Player, bytes: buffer) => void): void;
|
|
20
|
+
/** Sends an encoded frame to the server. */
|
|
17
21
|
SendToServer(bytes: buffer): void;
|
|
22
|
+
/** Registers the client callback for incoming server frames. */
|
|
18
23
|
ListenClient(callback: (this: void, bytes: buffer) => void): void;
|
|
24
|
+
/** Disconnects the client listener when Client.Stop runs. */
|
|
19
25
|
Release?(): void;
|
|
20
26
|
}
|
|
21
27
|
|
|
22
28
|
export interface Connection {
|
|
23
29
|
readonly Connected: boolean;
|
|
30
|
+
/** Stops this connection from receiving events. */
|
|
24
31
|
Disconnect(): void;
|
|
25
32
|
}
|
|
26
33
|
/** Read-only event surface. Scribe owns firing and destroying these signals. */
|
|
27
34
|
export interface Signal<Args extends unknown[]> {
|
|
35
|
+
/** Runs the callback on each event until disconnected. */
|
|
28
36
|
Connect(callback: (this: void, ...args: Args) => void): Connection;
|
|
37
|
+
/** Runs the callback on the next event only. */
|
|
29
38
|
Once(callback: (this: void, ...args: Args) => void): Connection;
|
|
39
|
+
/** Yields until the next event and returns its arguments. */
|
|
30
40
|
Wait(): LuaTuple<Args>;
|
|
31
41
|
}
|
|
32
42
|
|
|
@@ -208,6 +218,7 @@ export type LogCode =
|
|
|
208
218
|
| "LISTENER_ERROR"
|
|
209
219
|
| "ON_PLAYER_INIT_ERROR"
|
|
210
220
|
| "ON_PLAYER_INIT_LEDGER"
|
|
221
|
+
| "ON_PLAYER_INIT_SESSION"
|
|
211
222
|
| "PLAYER_LEAVING_HOOK_SLOW"
|
|
212
223
|
| "SANDBOXED"
|
|
213
224
|
| "SERVER_STARTED"
|
|
@@ -235,7 +246,7 @@ declare const requestFailedBrand: unique symbol;
|
|
|
235
246
|
export interface RequestFailedMarker { readonly [requestFailedBrand]: true; }
|
|
236
247
|
export type RequestFailure = LuaTuple<[false, RequestReason, RequestFailedMarker]>;
|
|
237
248
|
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";
|
|
249
|
+
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" | "invalid IdempotencyKey";
|
|
239
250
|
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
251
|
export type OperationResult = LuaTuple<[boolean, string | undefined]>;
|
|
241
252
|
|
|
@@ -251,6 +262,7 @@ export interface UpdateOfflineOptions { Validate?: boolean; }
|
|
|
251
262
|
export interface RestoreOptions { RollBackReserved?: boolean; }
|
|
252
263
|
export interface CooldownOptions { IncludeOfflineTime?: boolean; }
|
|
253
264
|
export interface MigrationContext {
|
|
265
|
+
/** Waits for request allowance; call the returned release after issuing requests. */
|
|
254
266
|
readonly AwaitBudget: (this: void, requestType: string, count?: number, timeout?: number) => LuaTuple<[boolean, Disconnect]>;
|
|
255
267
|
}
|
|
256
268
|
|
|
@@ -330,10 +342,15 @@ export type ExchangeLeg =
|
|
|
330
342
|
export interface OpenLeg { Path: Path; Kind: "Key" | "Qty" | "Stack"; Key?: unknown; Amount?: number; }
|
|
331
343
|
export interface OpenExchange { Id: string; State: "Claimed" | "Staked" | "Delivering"; Partner?: number; Staked: OpenLeg[]; Owed: OpenLeg[]; Since?: number; }
|
|
332
344
|
export interface ExchangeAPI {
|
|
345
|
+
/** Trades baskets between loaded players; a verdict can precede delivery. */
|
|
333
346
|
readonly Attempt: (this: void, playerA: Player, basketA: ReadonlyArray<ExchangeLeg>, playerB: Player, basketB: ReadonlyArray<ExchangeLeg>) => LuaTuple<["Committed" | "Aborted" | undefined, string | undefined]>;
|
|
347
|
+
/** Lists the player's unfinished exchanges and held value. */
|
|
334
348
|
readonly Open: (this: void, player: Player) => OpenExchange[];
|
|
349
|
+
/** Drops an unstaked claim only when no verdict exists. */
|
|
335
350
|
readonly Discard: (this: void, exchangeId: string) => OperationResult;
|
|
351
|
+
/** Settles a stalled exchange; an existing verdict wins. */
|
|
336
352
|
readonly Settle: (this: void, exchangeId: string, verdict: "Commit" | "Abort") => OperationResult;
|
|
353
|
+
/** Moves a parked delivery to another key in the same container. */
|
|
337
354
|
readonly Redirect: (this: void, exchangeId: string, userId: number, newKey: string) => OperationResult;
|
|
338
355
|
}
|
|
339
356
|
|
|
@@ -342,7 +359,11 @@ export interface MetricObservation { Count: number; Average: number; Max: number
|
|
|
342
359
|
export type Metrics = { [name: string]: number | MetricObservation };
|
|
343
360
|
export interface Percentiles { P50: number; P90: number; P99: number; Samples: number; Age: number; Window: number; }
|
|
344
361
|
export type PercentileSnapshot = { [name: string]: Percentiles };
|
|
345
|
-
export interface AddonAction {
|
|
362
|
+
export interface AddonAction {
|
|
363
|
+
/** Runs the action with arguments from the Studio plugin. */
|
|
364
|
+
Run: (this: void, args: unknown) => unknown;
|
|
365
|
+
Writes?: boolean;
|
|
366
|
+
}
|
|
346
367
|
export type AddonActions = { [name: string]: AddonAction };
|
|
347
368
|
export interface ConfigureOptions { AutoSaveInterval?: number; }
|
|
348
369
|
export interface StatusThresholds { FailWindow?: number; FailCount?: number; RecoverStreak?: number; }
|
package/types/index.d.ts
CHANGED
|
@@ -6,63 +6,118 @@ declare const Scribe: Scribe.ScribeModule;
|
|
|
6
6
|
|
|
7
7
|
declare namespace Scribe {
|
|
8
8
|
interface ScribeModule {
|
|
9
|
+
/** Creates the server and client APIs from a shared template. */
|
|
9
10
|
<T, S = {}, C = {}>(options: API.ScribeOptions<T, S, C>): API.Bundle<T, S, C>;
|
|
11
|
+
/** Creates the server and client APIs from a shared template. */
|
|
10
12
|
readonly new: <T, S = {}, C = {}>(this: void, options: API.ScribeOptions<T, S, C>) => API.Bundle<T, S, C>;
|
|
11
13
|
readonly Version: string;
|
|
14
|
+
/** Keeps a field and its subtree off the client. */
|
|
12
15
|
readonly ServerOnly: <T>(this: void, value: T) => Schema.ServerOnly<T>;
|
|
16
|
+
/** Replicates a root field to every client. */
|
|
13
17
|
readonly Shared: <T>(this: void, value: T) => Schema.Shared<T>;
|
|
18
|
+
/** Keeps a root field unsaved; its visibility wrappers still apply. */
|
|
14
19
|
readonly Session: <T>(this: void, value: T) => Schema.Session<T>;
|
|
20
|
+
/** Declares integer data with optional bounds. */
|
|
15
21
|
readonly Int: (this: void, value: number, meta?: NumberMeta) => number;
|
|
22
|
+
/** Declares floating-point data with optional bounds and wire precision. */
|
|
16
23
|
readonly Number: (this: void, value: number, meta?: FloatMeta) => number;
|
|
24
|
+
/** Declares large-range numbers; numeric strings are limited to 256 bytes. */
|
|
17
25
|
readonly Big: (this: void, value?: number | string, meta?: BigMeta) => Schema.BigSchema;
|
|
26
|
+
/** Declares string data with an optional byte limit. */
|
|
18
27
|
readonly String: (this: void, value: string, meta?: StringMeta) => string;
|
|
28
|
+
/** Restricts a string field to the declared members. */
|
|
19
29
|
readonly Enum: <K extends string>(this: void, value: NoInfer<K>, members: readonly K[]) => Schema.EnumValue<K>;
|
|
30
|
+
/** Stores up to 32 named booleans as one field. */
|
|
20
31
|
readonly Flags: <K extends string>(this: void, members: readonly K[]) => Schema.Flags<K>;
|
|
32
|
+
/** Declares a leaf reset to its default after SetTimed expires. */
|
|
21
33
|
readonly Timed: <T>(this: void, value: T) => Schema.Timed<T>;
|
|
34
|
+
/** Builds a default per profile with the supplied factory. */
|
|
22
35
|
readonly Dynamic: <T>(this: void, factory: (this: void) => T) => T;
|
|
23
|
-
/**
|
|
36
|
+
/** Computes a read-only field from paths; annotate compute arguments explicitly. */
|
|
24
37
|
readonly Derived: <T, A extends unknown[]>(this: void, output: T, inputs: readonly string[], compute: (this: void, ...args: A) => Schema.ValueOf<T>) => Schema.Derived<T>;
|
|
38
|
+
/** Allows an absent leaf value without seeding the inner default. */
|
|
25
39
|
readonly Optional: <T>(this: void, value: T) => Schema.Optional<T>;
|
|
40
|
+
/** Declares a typed array with optional size and eviction limits. */
|
|
26
41
|
readonly ArrayOf: <T>(this: void, shape: T, options?: ArrayOpts) => Schema.ArrayOf<T>;
|
|
42
|
+
/** Declares unique scalar members with an optional size limit. */
|
|
27
43
|
readonly SetOf: <T>(this: void, element: T, options?: SetOpts) => Schema.SetOf<T>;
|
|
44
|
+
/** Declares a map with integer or string keys and a value schema. */
|
|
28
45
|
readonly MapOf: <K extends "integer" | "string", T>(this: void, keyType: K, shape: T, options?: DictOpts) => Schema.MapOf<K, T>;
|
|
46
|
+
/** Declares string-keyed values with a schema and optional limits. */
|
|
29
47
|
readonly DictOf: <T>(this: void, shape: T, options?: DictOpts) => Schema.DictOf<T>;
|
|
48
|
+
/** Declares Vector3 data, packed for storage and replication. */
|
|
30
49
|
readonly Vector3: (this: void, value: Vector3) => Vector3;
|
|
50
|
+
/** Declares Vector2 data, packed for storage and replication. */
|
|
31
51
|
readonly Vector2: (this: void, value: Vector2) => Vector2;
|
|
52
|
+
/** Declares Vector3int16 data, packed for storage and replication. */
|
|
32
53
|
readonly Vector3int16: (this: void, value: Vector3int16) => Vector3int16;
|
|
54
|
+
/** Declares Vector2int16 data, packed for storage and replication. */
|
|
33
55
|
readonly Vector2int16: (this: void, value: Vector2int16) => Vector2int16;
|
|
56
|
+
/** Declares packed CFrame data; Precision = "exact" preserves its f32 components. */
|
|
34
57
|
readonly CFrame: (this: void, value: CFrame, meta?: CFrameMeta) => CFrame;
|
|
58
|
+
/** Declares Color3 data, packed for storage and replication. */
|
|
35
59
|
readonly Color3: (this: void, value: Color3) => Color3;
|
|
60
|
+
/** Declares BrickColor data, packed for storage and replication. */
|
|
36
61
|
readonly BrickColor: (this: void, value: BrickColor) => BrickColor;
|
|
62
|
+
/** Declares UDim data, packed for storage and replication. */
|
|
37
63
|
readonly UDim: (this: void, value: UDim) => UDim;
|
|
64
|
+
/** Declares UDim2 data, packed for storage and replication. */
|
|
38
65
|
readonly UDim2: (this: void, value: UDim2) => UDim2;
|
|
66
|
+
/** Declares Rect data, packed for storage and replication. */
|
|
39
67
|
readonly Rect: (this: void, value: Rect) => Rect;
|
|
68
|
+
/** Declares NumberRange data, packed for storage and replication. */
|
|
40
69
|
readonly NumberRange: (this: void, value: NumberRange) => NumberRange;
|
|
70
|
+
/** Declares NumberSequence data, packed for storage and replication. */
|
|
41
71
|
readonly NumberSequence: (this: void, value: NumberSequence) => NumberSequence;
|
|
72
|
+
/** Declares ColorSequence data, packed for storage and replication. */
|
|
42
73
|
readonly ColorSequence: (this: void, value: ColorSequence) => ColorSequence;
|
|
74
|
+
/** Declares DateTime data, packed for storage and replication. */
|
|
43
75
|
readonly DateTime: (this: void, value: DateTime) => DateTime;
|
|
76
|
+
/** Declares EnumItem data, packed for storage and replication. */
|
|
44
77
|
readonly EnumItem: <T extends EnumItem>(this: void, value: T) => T;
|
|
78
|
+
/** Declares Font data, packed for storage and replication. */
|
|
45
79
|
readonly Font: (this: void, value: Font) => Font;
|
|
80
|
+
/** Declares PhysicalProperties data, packed for storage and replication. */
|
|
46
81
|
readonly PhysicalProperties: (this: void, value: PhysicalProperties) => PhysicalProperties;
|
|
82
|
+
/** Formats a number or Big value with suffixes and decimal places. */
|
|
47
83
|
readonly Short: (this: void, value?: number | Schema.BigValue, decimals?: number) => string;
|
|
84
|
+
/** Replaces suffixes used by Short; the first suffix must be empty. */
|
|
48
85
|
readonly SetShortSuffixes: (this: void, suffixes: readonly string[]) => void;
|
|
86
|
+
/** Sets process-wide options before any bundle is built; conflicting calls error. */
|
|
49
87
|
readonly Configure: (this: void, config: Common.ConfigureOptions) => void;
|
|
88
|
+
/** Returns the server bundle prefix, or PLAYER_ before setup and on clients. */
|
|
50
89
|
readonly GetProfileKeyPrefix: (this: void) => string;
|
|
90
|
+
/** Returns current DataStore health. */
|
|
51
91
|
readonly GetStatus: (this: void) => Common.Status;
|
|
92
|
+
/** Fires when data-service health changes, with the new and previous status. */
|
|
52
93
|
readonly OnStatusChanged: Common.Signal<[Common.Status, Common.Status]>;
|
|
94
|
+
/** Fires for each Error or Fatal log entry. */
|
|
53
95
|
readonly OnIssue: Common.Signal<[Common.LogEntry]>;
|
|
96
|
+
/** Adds a filtered, bounded log sink; returns its disconnect function. */
|
|
54
97
|
readonly AddLogSink: (this: void, callback: (this: void, entry: Common.LogEntry) => void, options?: Common.LogSinkOptions) => Schema.Disconnect;
|
|
98
|
+
/** Registers plugin actions; returned cleanup removes only this registration. */
|
|
55
99
|
readonly RegisterAddon: (this: void, name: string, actions: Common.AddonActions) => Schema.Disconnect;
|
|
100
|
+
/** Returns filtered retained logs, oldest first; Limit keeps the newest entries. */
|
|
56
101
|
readonly GetRecentLogs: (this: void, filter?: Common.LogFilter) => Common.LogEntry[];
|
|
102
|
+
/** Returns this context's counters and distribution summaries. */
|
|
57
103
|
readonly GetMetrics: (this: void) => Common.Metrics;
|
|
104
|
+
/** Returns recent distribution percentiles with sample age and window size. */
|
|
58
105
|
readonly GetPercentiles: (this: void) => Common.PercentileSnapshot;
|
|
106
|
+
/** Reads current DataStore allowances; Available is false if the query fails. */
|
|
59
107
|
readonly GetBudgetSnapshot: (this: void) => Common.BudgetSnapshot;
|
|
108
|
+
/** Returns cached board health without DataStore requests; empty on clients. */
|
|
60
109
|
readonly GetLeaderboardSnapshot: (this: void) => Common.LeaderboardSnapshotEntry[];
|
|
110
|
+
/** Distinguishes framework request failures from handler replies. */
|
|
61
111
|
readonly RequestFailed: Common.RequestFailedMarker;
|
|
112
|
+
/** Codec helpers for packing and unpacking Roblox datatypes. */
|
|
62
113
|
readonly Datatypes: {
|
|
114
|
+
/** Checks whether a datatype has a registered codec. */
|
|
63
115
|
readonly IsSupported: (this: void, name: string) => boolean;
|
|
116
|
+
/** Lists supported precision options, or returns `undefined` when none exist. */
|
|
64
117
|
readonly PrecisionValues: (this: void, name: string) => string[] | undefined;
|
|
118
|
+
/** Encodes a supported datatype into a buffer. */
|
|
65
119
|
readonly Pack: <K extends keyof DatatypeValues>(this: void, name: K, value: DatatypeValues[K], precision?: K extends "CFrame" ? "exact" : never) => buffer;
|
|
120
|
+
/** Decodes a buffer into the named datatype. */
|
|
66
121
|
readonly Unpack: <K extends keyof DatatypeValues>(this: void, name: K, bytes: buffer) => DatatypeValues[K];
|
|
67
122
|
readonly NONFINITE: "Scribe:nonfinite:";
|
|
68
123
|
};
|
|
@@ -109,7 +164,7 @@ declare namespace Scribe {
|
|
|
109
164
|
export type ClientSchema<T> = Schema.ClientSchema<T>;
|
|
110
165
|
export type SharedSchema<T> = Schema.SharedSchema<T>;
|
|
111
166
|
export type ReadableNode<T> = Schema.ReadableNode<T>;
|
|
112
|
-
export type Accessor<T, Root extends boolean = false, Missing extends boolean = false, ReadOnly extends boolean = false, Closed extends boolean = false> = Schema.Accessor<T, Root, Missing, ReadOnly, Closed>;
|
|
167
|
+
export type Accessor<T, Root extends boolean = false, Missing extends boolean = false, ReadOnly extends boolean = false, Closed extends boolean = false, Client extends boolean = false> = Schema.Accessor<T, Root, Missing, ReadOnly, Closed, Client>;
|
|
113
168
|
export type PlayerData<T> = Schema.PlayerData<T>;
|
|
114
169
|
export type ReadonlyAccessor<T, Root extends boolean = false> = Schema.ReadonlyAccessor<T, Root>;
|
|
115
170
|
export type NumericPaths<T, IncludeBig extends boolean = false, Depth extends unknown[] = []> = Schema.NumericPaths<T, IncludeBig, Depth>;
|
|
@@ -208,7 +263,7 @@ declare namespace Scribe {
|
|
|
208
263
|
interface ScribeModule {
|
|
209
264
|
readonly Reason: { readonly LoadFailed: "load-failed"; readonly MigrationFailed: "migration-failed"; readonly Erasing: "erasing"; readonly SessionEnded: "session-ended"; readonly PlayerLeft: "player-left"; readonly Shutdown: "shutdown"; readonly StillLoading: "still-loading"; readonly Timeout: "timeout"; };
|
|
210
265
|
readonly RequestReason: { readonly RateLimited: "rate-limited"; readonly NotReady: "not-ready"; readonly UnknownCommand: "unknown-command"; readonly BadArgs: "bad-args"; readonly BadIdempotencyKey: "bad-idempotency-key"; readonly Error: "error"; readonly ReplyEncodeFailed: "reply-encode-failed"; readonly Timeout: "timeout"; readonly SendFailed: "send-failed"; readonly EditMode: "edit-mode"; readonly MockError: "mock-error"; };
|
|
211
|
-
readonly PurchaseReason: { readonly DataNotLoaded: "player data not loaded"; readonly InvalidCostSpec: "invalid Cost spec"; readonly InvalidCostAmount: "invalid Cost amount"; readonly InvalidCostPath: "invalid cost path"; readonly CostPathNotSpendable: "cost path is not a spendable number"; readonly InsufficientFunds: "insufficient funds"; readonly PaidRandomRestricted: "paid random items are not available for this account"; readonly PolicyPending: "cannot check account settings right now; try again in a moment"; };
|
|
266
|
+
readonly PurchaseReason: { readonly DataNotLoaded: "player data not loaded"; readonly InvalidCostSpec: "invalid Cost spec"; readonly InvalidCostAmount: "invalid Cost amount"; readonly InvalidCostPath: "invalid cost path"; readonly CostPathNotSpendable: "cost path is not a spendable number"; readonly InsufficientFunds: "insufficient funds"; readonly PaidRandomRestricted: "paid random items are not available for this account"; readonly PolicyPending: "cannot check account settings right now; try again in a moment"; readonly InvalidIdempotencyKey: "invalid IdempotencyKey"; };
|
|
212
267
|
readonly GiftReason: { readonly ProductRetired: "product retired"; readonly BuyerDataNotLoaded: "buyer data not loaded"; readonly InvalidRecipient: "invalid recipient"; readonly CannotGiftYourself: "cannot gift yourself"; readonly GiftCooldown: "gift cooldown"; readonly TooManyPending: "too many pending gifts"; readonly DataServicesDown: "data services are experiencing issues; try again later"; readonly RecipientAlreadyOwns: "recipient already owns this"; readonly CreditReserveFailed: "could not reserve gift credit; try again later"; readonly DeliveryFailed: "could not deliver gift; try again later"; readonly DeliveryUnconfirmed: "gift delivery could not be confirmed; do not send it again"; readonly AlreadyPending: "a gift of this item is already pending; try again shortly"; readonly IntentRecordFailed: "could not record gift intent; try again later"; readonly PaidRandomRestricted: "paid random items are not available for this account"; readonly PolicyPending: "cannot check account settings right now; try again in a moment"; };
|
|
213
268
|
readonly ProductState: { readonly Purchasable: "purchasable"; readonly Owned: "owned"; readonly PaidRandomRestricted: "paid-random-restricted"; readonly PolicyPending: "policy-pending"; readonly NotLoaded: "not-loaded"; };
|
|
214
269
|
readonly OpKind: { readonly Init: "Init"; readonly Set: "Set"; readonly Insert: "Insert"; readonly Remove: "Remove"; readonly Clear: "Clear"; };
|