@rbxts/scribe 2.5.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.
Files changed (56) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE +21 -0
  3. package/README.md +100 -0
  4. package/Scribe-source-map.json +1 -0
  5. package/licenses/ProfileStore-Apache-2.0.txt +201 -0
  6. package/package.json +32 -0
  7. package/src/Client/DebugHook.luau +457 -0
  8. package/src/Client/init.luau +1607 -0
  9. package/src/Internal/Addons.luau +68 -0
  10. package/src/Internal/Big.luau +582 -0
  11. package/src/Internal/Budget.luau +377 -0
  12. package/src/Internal/Clock.luau +75 -0
  13. package/src/Internal/Config.luau +17 -0
  14. package/src/Internal/Conform.luau +400 -0
  15. package/src/Internal/Datatypes.luau +653 -0
  16. package/src/Internal/Defaults.luau +12 -0
  17. package/src/Internal/Derived.luau +428 -0
  18. package/src/Internal/Exchange.luau +556 -0
  19. package/src/Internal/ExchangeLeg.luau +1368 -0
  20. package/src/Internal/ExchangeVerdict.luau +179 -0
  21. package/src/Internal/Failure.luau +148 -0
  22. package/src/Internal/Health.luau +320 -0
  23. package/src/Internal/LeaderboardDiagnostics.luau +36 -0
  24. package/src/Internal/Log.luau +378 -0
  25. package/src/Internal/Marker.luau +76 -0
  26. package/src/Internal/Metrics.luau +152 -0
  27. package/src/Internal/Node.luau +3954 -0
  28. package/src/Internal/Profile.luau +69 -0
  29. package/src/Internal/Rng.luau +83 -0
  30. package/src/Internal/Sched.luau +56 -0
  31. package/src/Internal/Signal.luau +199 -0
  32. package/src/Internal/Store/ProfileStore.luau +3019 -0
  33. package/src/Internal/Store/init.luau +18 -0
  34. package/src/Internal/StudioCodec.luau +155 -0
  35. package/src/Internal/Template.luau +1848 -0
  36. package/src/Internal/Transport.luau +169 -0
  37. package/src/Internal/Util.luau +517 -0
  38. package/src/Internal/Version.luau +4 -0
  39. package/src/Internal/Wire.luau +1283 -0
  40. package/src/Server/Analytics.luau +223 -0
  41. package/src/Server/Commands.luau +728 -0
  42. package/src/Server/DebugHook.luau +1490 -0
  43. package/src/Server/Exchanges.luau +737 -0
  44. package/src/Server/Leaderboards.luau +2143 -0
  45. package/src/Server/Monetization.luau +3212 -0
  46. package/src/Server/Persistence.luau +3775 -0
  47. package/src/Server/Replication.luau +1253 -0
  48. package/src/Server/ServerStore.luau +81 -0
  49. package/src/Server/Timed.luau +579 -0
  50. package/src/Server/init.luau +672 -0
  51. package/src/Types.luau +480 -0
  52. package/src/init.luau +2231 -0
  53. package/types/api.d.ts +252 -0
  54. package/types/common.d.ts +355 -0
  55. package/types/index.d.ts +226 -0
  56. package/types/schema.d.ts +276 -0
package/src/Types.luau ADDED
@@ -0,0 +1,480 @@
1
+ --!strict
2
+ -- Shared type definitions for Scribe.
3
+
4
+ export type PathSegment = string | number
5
+ export type Path = { PathSegment }
6
+
7
+ export type OpKind = "Init" | "Set" | "Insert" | "Remove" | "Clear"
8
+
9
+ export type Op = {
10
+ Kind: OpKind,
11
+ Path: Path,
12
+ Value: unknown?,
13
+ Index: number?,
14
+ }
15
+
16
+ export type ScribeTransport = {
17
+ Name: string,
18
+ -- The largest buffer this channel wants handed to it in one call. Read once at
19
+ -- construction, and it wins over MaxOutboundBytes only when it is smaller, so it
20
+ -- can never raise a game's configured budget. Declare it when the adapter's own
21
+ -- framing changes the arithmetic, such as base64 inflating by 4/3.
22
+ MaxFrameBytes: number?,
23
+ -- Server
24
+ SendToClient: (self: any, player: Player, bytes: buffer) -> (),
25
+ SendToAllClients: ((self: any, bytes: buffer) -> ())?,
26
+ ListenServer: (self: any, callback: (player: Player, bytes: buffer) -> ()) -> (),
27
+ -- Client
28
+ SendToServer: (self: any, bytes: buffer) -> (),
29
+ ListenClient: (self: any, callback: (bytes: buffer) -> ()) -> (),
30
+ -- Optional. Client.Stop calls it to disconnect what ListenClient connected.
31
+ Release: ((self: any) -> ())?,
32
+ }
33
+
34
+ export type LogLevel = "Debug" | "Info" | "Warn" | "Error" | "Fatal"
35
+ export type LogSinkOptions = { Level: LogLevel?, MaxQueued: number? }
36
+ export type LogCategory =
37
+ "Persistence"
38
+ | "Replication"
39
+ | "Transport"
40
+ | "Commands"
41
+ | "Leaderboards"
42
+ | "Monetization"
43
+ | "Gifting"
44
+ | "Integrity"
45
+ | "Lifecycle"
46
+ | "Derived"
47
+ | "Exchanges"
48
+
49
+ export type LogCode =
50
+ -- Persistence
51
+ "DATASTORE_CRITICAL"
52
+ | "DATASTORE_RECOVERED"
53
+ | "EXPORT_ENCODE_FAIL"
54
+ | "LEGACY_IMPORTED"
55
+ | "LEGACY_IMPORT_FAIL"
56
+ | "MIGRATED"
57
+ | "MESSAGE_SEND_FAIL"
58
+ | "MESSAGE_QUEUE_FULL"
59
+ | "MESSAGE_NO_LISTENER"
60
+ | "MESSAGE_HANDLER_ERROR"
61
+ | "MESSAGE_HANDLER_STALLED"
62
+ | "MIGRATION_FAIL"
63
+ | "MIGRATION_RECONCILE_DEPENDENT"
64
+ | "MIGRATION_RESERVED_DISCARDED"
65
+ | "MODE_OVERRIDES_LEGACY"
66
+ | "OFFLINE_READ_FAIL"
67
+ | "OFFLINE_WRITE_FAIL"
68
+ | "NOSAVE_WRITE_REFUSED"
69
+ | "PROFILE_ERASED"
70
+ | "PROFILE_ERASE_FAIL"
71
+ | "PROFILE_ERASE_PROGRESS_FAIL"
72
+ | "PROFILE_ERASE_RESUMED"
73
+ | "PROFILE_LOADED"
74
+ | "PROFILE_LOAD_FAIL"
75
+ | "PROFILE_RESET"
76
+ | "PROFILE_RESTORED"
77
+ | "PROFILE_RESTORE_FAIL"
78
+ | "RESTORE_RESERVED_PRESERVED"
79
+ | "PROFILE_SIZE"
80
+ | "SLOW_LOAD"
81
+ | "SLOW_IMPORT"
82
+ | "SAVE_WAIT_TIMEOUT"
83
+ | "PROFILE_STORE_ERROR"
84
+ | "PROFILE_STORE_SIGNAL_MISSING"
85
+ | "PROFILE_TOO_LARGE"
86
+ | "PROFILE_UNPERSISTABLE"
87
+ | "PROFILE_VERSION_AHEAD"
88
+ | "SAVE_INTERVAL_CLAMPED"
89
+ | "WIPE_GUARD_RATIO_CLAMPED"
90
+ | "HEALTH_THRESHOLDS_CONFLICT"
91
+ | "SAVE_INTERVAL_CONFLICT"
92
+ | "SAVE_INTERVAL_FAIL"
93
+ | "SAVE_INTERVAL_SET"
94
+ | "SHUTDOWN_DONE"
95
+ | "SHUTDOWN_FLUSH"
96
+ | "SIM_LOAD_FAILURE"
97
+ | "SIM_SESSION_STEAL"
98
+ | "STATUS_CHANGED"
99
+ | "UNKNOWN_ROOT_KEYS"
100
+ | "VERSION_QUERY_FAIL"
101
+ | "VERSION_READ_FAIL"
102
+ -- Integrity
103
+ | "ANALYTICS_FAIL"
104
+ | "ANOMALY"
105
+ | "ECONOMY_FIELDS_OVERFLOW"
106
+ | "ECONOMY_FIELD_UNDECLARED"
107
+ | "PROFILE_OVERWRITTEN"
108
+ | "PROFILE_TOO_DEEP"
109
+ | "PROFILE_SCHEMA_VIOLATION"
110
+ | "TIMED_SWEEP_FAIL"
111
+ | "WIPE_GUARD_BLOCKED"
112
+ | "WIPE_GUARD_CLEARED"
113
+ | "WIPE_GUARD_FORCED"
114
+ | "WIPE_GUARD_TRIPPED"
115
+ -- Replication
116
+ | "CLIENT_HANDSHAKE_TIMEOUT"
117
+ | "FRAGMENT_REFUSED"
118
+ | "INIT_APPLIED"
119
+ | "INIT_SEND_FAIL"
120
+ | "MIRROR_RESYNC"
121
+ | "INIT_SENT"
122
+ | "INIT_UNDELIVERED"
123
+ | "OP_BEFORE_INIT"
124
+ | "OUTBOUND_OVERSIZE"
125
+ | "PROTOCOL_MISMATCH"
126
+ | "SCHEMA_MISMATCH"
127
+ | "SERIALIZE_FAIL"
128
+ | "SNAPSHOT_ROOT_DROPPED"
129
+ -- Transport
130
+ | "INBOUND_OVERSIZE"
131
+ | "INBOUND_OVERSIZE_LIMIT"
132
+ | "INBOUND_RATE_LIMITED"
133
+ | "INBOUND_WORK_LIMIT"
134
+ | "MALFORMED_FRAME"
135
+ | "MALFORMED_FRAME_LIMIT"
136
+ | "SEND_FAIL"
137
+ -- Commands
138
+ | "COMMAND_BAD_ARGS"
139
+ | "COMMAND_BAD_IDEMPOTENCY_KEY"
140
+ | "COMMAND_ERROR"
141
+ | "COMMAND_IDEM_EVICTED"
142
+ | "COMMAND_IDEM_SATURATED"
143
+ | "COMMAND_RATE_LIMITED"
144
+ | "COMMAND_REPLY_ENCODE_FAIL"
145
+ | "COMMAND_REPLY_TRUNCATED"
146
+ | "COMMAND_UNKNOWN"
147
+ | "SIM_COMMAND"
148
+ -- Monetization
149
+ | "GRANT_FAIL"
150
+ | "GRANT_PARTIAL"
151
+ | "GRANT_SEEDED_ELEMENT"
152
+ | "RECEIPT_IN_FLIGHT"
153
+ | "RECEIPT_HISTORY_FULL"
154
+ | "OWNERSHIP_CHECK_FAIL"
155
+ | "PASS_PURCHASE_UNCONFIRMED"
156
+ | "PERK_GRANTED"
157
+ | "PERK_REVOKED"
158
+ | "PRODUCT_INFO_FAIL"
159
+ | "POLICY_READ_FAIL"
160
+ | "PAID_RANDOM_RECEIPT"
161
+ | "PRODUCT_INFO_THROTTLED"
162
+ | "PURCHASE_DUPLICATE"
163
+ | "PURCHASE_CLAIM_EVICTED"
164
+ | "PURCHASE_ID_EVICTED"
165
+ | "RECEIPT_DUPLICATE"
166
+ | "RECEIPT_GRANTED"
167
+ | "RECEIPT_HANDLER_BOUND"
168
+ | "RECEIPT_OFFLINE_RETRY"
169
+ | "RECEIPT_RETRY"
170
+ | "RECEIPT_UNKNOWN_PRODUCT"
171
+ | "SIM_RECEIPT"
172
+ | "UNDECLARED_CATEGORY"
173
+ | "UNDECLARED_PERK"
174
+ | "UNKNOWN_OWNS_KEY"
175
+ -- Gifting
176
+ | "GIFT_AIM_CAP_REACHED"
177
+ | "GIFT_AIM_EXPIRED"
178
+ | "GIFT_AIM_SETTLED"
179
+ | "GIFT_CREDIT_ISSUED"
180
+ | "GIFT_CREDIT_REFUND_FAIL"
181
+ | "GIFT_CREDIT_UNCONFIRMED"
182
+ | "GIFT_CREDIT_UNKNOWN_PRODUCT"
183
+ | "GIFT_CREDIT_USED"
184
+ | "GIFT_DELIVERY_RETRY"
185
+ | "GIFT_INVALID_RECIPIENT"
186
+ | "GIFT_INTENT_EXPIRED"
187
+ | "GIFT_INTENT_WRITE_FAIL"
188
+ | "GIFT_NO_INTENT"
189
+ | "GIFT_RECEIPT_GRANTED"
190
+ | "GIFT_RECIPIENT_ALREADY_OWNS"
191
+ | "GIFT_UNKNOWN_PRODUCT"
192
+ | "RECEIPT_DECLINED_PENDING_CREDIT"
193
+ | "RECEIPT_HELD"
194
+ -- Leaderboards
195
+ | "LB_ERASE_FAIL"
196
+ | "LB_INTERVAL_CLAMPED"
197
+ | "LB_QUEUE_OVERFLOW"
198
+ | "LB_READ_FAIL"
199
+ | "LB_SCORE_OUT_OF_RANGE"
200
+ | "LB_SHUTDOWN_FLUSH"
201
+ | "LB_STAT_RESOLVE_FAIL"
202
+ | "LB_UNKNOWN_BOARD"
203
+ | "LB_BUDGET_DEFERRED"
204
+ | "LB_WRITE_DROPPED"
205
+ | "LB_WRITE_FAIL"
206
+ | "SIM_LB_FLUSH"
207
+ -- Exchanges
208
+ | "EXCHANGE_INIT_TAMPER"
209
+ | "EXCHANGE_PARKED"
210
+ | "EXCHANGE_REGISTRATION_REFUSED"
211
+ | "EXCHANGE_RESET_REFUSED"
212
+ | "EXCHANGE_RESOLVED"
213
+ | "EXCHANGE_RESOLVE_ERROR"
214
+ | "EXCHANGE_STORE_UNAVAILABLE"
215
+ | "EXCHANGE_UNRESOLVED"
216
+ -- Derived
217
+ | "DERIVED_ERROR"
218
+ | "DERIVED_FEEDBACK"
219
+ | "DERIVED_MISMATCH"
220
+ -- Lifecycle
221
+ | "API_NAME_COLLISION"
222
+ | "DEBUG_HOOK_ATTACHED"
223
+ | "DEBUG_HOOK_ATTRIBUTION"
224
+ | "DEBUG_HOOK_DUPLICATE"
225
+ | "DEBUG_HOOK_ERROR"
226
+ | "DEBUG_HOOK_FAIL"
227
+ | "DEBUG_HOOK_WRITES"
228
+ | "DEV_WARNING"
229
+ | "DYNAMIC_DEFAULT_FAILED"
230
+ | "LISTENER_ERROR"
231
+ | "ON_PLAYER_INIT_ERROR"
232
+ | "PLAYER_LEAVING_HOOK_SLOW"
233
+ | "SANDBOXED"
234
+ | "SERVER_STARTED"
235
+ | "SIM_STATUS"
236
+ | "SUBSYSTEM_HOOK_ERROR"
237
+ | "UNKNOWN_OPTION"
238
+
239
+ export type LogEntry = {
240
+ At: number,
241
+ Level: LogLevel,
242
+ Category: LogCategory,
243
+ Code: LogCode,
244
+ Message: string,
245
+ Context: { [string]: any }?,
246
+ }
247
+
248
+ export type Status = "Healthy" | "Degraded" | "Outage"
249
+
250
+ export type SessionState = "Loading" | "Ready" | "SessionEnded"
251
+ export type LoadPhase =
252
+ "WaitingForErase"
253
+ | "AcquiringSession"
254
+ | "ReadingProfile"
255
+ | "Retrying"
256
+ | "Initializing"
257
+ | "Importing"
258
+ | "ImportThrottled"
259
+
260
+ -- Why a data session ended, or why waiting for data did not produce a tree.
261
+ -- `WaitForData`'s second return, the `SessionEnded` signal and `GetState`'s stored
262
+ -- reason all use this exact set, so a caller can branch exhaustively.
263
+ export type LifecycleReason =
264
+ "load-failed" -- the profile could not be loaded (DataStore failure, or the session could not be acquired)
265
+ | "migration-failed" -- a migration step errored, so the profile was released unmigrated (fail-closed)
266
+ | "erasing" -- the profile is being erased, so the join was refused to let the erase finish
267
+ | "session-ended" -- the session ended while the player was still in the game (usually stolen by another server)
268
+ | "player-left" -- the player left; the most common reason by far
269
+ | "shutdown" -- the server is closing
270
+ | "still-loading" -- the wait elapsed while the load was still in flight, and may yet succeed
271
+ | "timeout" -- the wait elapsed and Scribe has no session for this player at all
272
+
273
+ -- The fixed reasons Scribe itself answers a Client.Request with. A handler may
274
+ -- return any (false, string) of its own, so a caller types the second return as
275
+ -- `string?` and treats a non-member as a handler message. Membership is not proof of
276
+ -- a framework refusal either: a handler can return `false, "timeout"`
277
+ -- byte-identically. RequestFailed at the bottom of this file, appended as a third
278
+ -- value to every refusal here, is the attribution; this union is only the vocabulary.
279
+ export type RequestReason =
280
+ "rate-limited" -- over CommandRateLimit; the handler never ran
281
+ | "not-ready" -- the caller's profile is not Ready
282
+ | "unknown-command" -- nothing is registered under that name
283
+ | "bad-args" -- arity or Args-spec mismatch
284
+ | "bad-idempotency-key" -- a key was sent to a command that is not Idempotent, or omitted from one that is
285
+ | "error" -- the handler threw; the traceback goes to COMMAND_ERROR, never to the client
286
+ | "reply-encode-failed" -- the handler succeeded but its return value could not be encoded
287
+ | "timeout" -- client-side: no reply within RequestTimeout
288
+ | "send-failed" -- client-side: the transport raised while sending
289
+ | "edit-mode" -- client-side: not running, and no MockCommand is registered
290
+ | "mock-error" -- client-side: edit mode, and the MockCommand handler threw
291
+
292
+ -- What PromptPurchase refuses with, or "purchasable".
293
+ export type ProductState = "purchasable" | "owned" | "paid-random-restricted" | "policy-pending" | "not-loaded"
294
+
295
+ -- The fixed refusals of Data.Purchase. A Grant that throws passes the transaction's
296
+ -- own error text through instead, so this is not exhaustive over the second return.
297
+ export type PurchaseReason =
298
+ "player data not loaded"
299
+ | "invalid Cost spec"
300
+ | "invalid Cost amount"
301
+ | "invalid cost path"
302
+ | "cost path is not a spendable number"
303
+ | "insufficient funds"
304
+ | "paid random items are not available for this account"
305
+ | "cannot check account settings right now; try again in a moment"
306
+
307
+ -- The fixed refusals of Data.PromptGift. Two more are interpolated (`unknown
308
+ -- product "<name>"` and `purchase prompt failed: <err>`) and cannot be members.
309
+ --
310
+ -- "could not deliver gift" and "gift delivery could not be confirmed" must not be
311
+ -- collapsed in a UI: the first means the gift did not go out and the buyer's credit
312
+ -- is back, the second means the write may have committed with its answer lost, so a
313
+ -- retry would mint a fresh gift id the recipient's dedupe cannot recognise and grant
314
+ -- twice off one payment.
315
+ export type GiftReason =
316
+ "buyer data not loaded"
317
+ | "invalid recipient"
318
+ | "cannot gift yourself"
319
+ | "gift cooldown"
320
+ | "product retired"
321
+ | "too many pending gifts"
322
+ | "data services are experiencing issues; try again later"
323
+ | "recipient already owns this"
324
+ | "could not reserve gift credit; try again later"
325
+ | "could not deliver gift; try again later"
326
+ | "gift delivery could not be confirmed; do not send it again"
327
+ | "a gift of this item is already pending; try again shortly"
328
+ | "could not record gift intent; try again later"
329
+ | "paid random items are not available for this account"
330
+ | "cannot check account settings right now; try again in a moment"
331
+
332
+ export type SaveInfo = {
333
+ LastSaveAt: number?,
334
+ LastResult: ("Ok" | "Fail")?,
335
+ Dirty: boolean,
336
+ Size: number?, -- approx bytes of the last successful save (nil before the first)
337
+ }
338
+
339
+ export type Visibility = "Replicated" | "ServerOnly" | "Shared"
340
+
341
+ -- The read shape of a Scribe.Big, spelled out here rather than imported so Types
342
+ -- stays dependency-free. Kept in sync with Internal.Big.
343
+ export type BigScore = {
344
+ M: number,
345
+ E: number,
346
+ Short: (self: any, decimals: number?) -> string,
347
+ ToNumber: (self: any) -> number,
348
+ Log10: (self: any) -> number,
349
+ }
350
+
351
+ export type LeaderboardEntry = {
352
+ Rank: number,
353
+ UserId: number,
354
+ Name: string,
355
+ -- A big board hands back the big itself, not the packed OrderedDataStore key,
356
+ -- so this is not always a number.
357
+ Score: number | BigScore,
358
+ }
359
+
360
+ export type LeaderboardStatus = "Starting" | "Healthy" | "Degraded"
361
+ export type LeaderboardStatusInfo = {
362
+ Status: LeaderboardStatus,
363
+ PendingWrites: number,
364
+ RetryingWrites: number,
365
+ RejectedWrites: number,
366
+ LastReadAt: number?,
367
+ ReadAge: number?,
368
+ LastWriteAt: number?,
369
+ LastReadError: string?,
370
+ LastWriteError: string?,
371
+ }
372
+ export type LeaderboardSnapshotEntry = LeaderboardStatusInfo & { BundleId: number, Name: string }
373
+
374
+ export type LeaderboardConfig = {
375
+ Stat: string,
376
+ Limit: number?,
377
+ Scale: number?,
378
+ SigFigs: number?, -- Scribe.Big stats only: ranking-key significant figures, 1 to 15 (default 12)
379
+ Replicate: boolean?, -- default false: server-only (Data.GetLeaderboard on the server); true streams the board to clients
380
+ Period: ("Daily" | "Weekly")?, -- a board that resets; nil is lifetime
381
+ Mode: ("Gain" | "Peak")?, -- with Period: rank the gain since it began (default) or the peak seen in it
382
+ Scope: ("Global" | "Server")?, -- "Server" ranks the players on this server, with no store behind it
383
+ }
384
+
385
+ export type ProductConfig = {
386
+ Id: number,
387
+ Category: string?,
388
+ Grant: ((data: any) -> ())?,
389
+ Grants: string?,
390
+ PaidRandom: boolean?,
391
+ }
392
+
393
+ export type PassConfig = {
394
+ Id: number,
395
+ Category: string?,
396
+ }
397
+
398
+ export type PurchaseSpec = {
399
+ Cost: { Path: string, Amount: number },
400
+ Category: string?,
401
+ ItemId: string,
402
+ Grant: ((data: any) -> ())?,
403
+ Meta: { [string]: any }?,
404
+ -- Optional. Two calls carrying the same key apply once: the repeat returns the
405
+ -- original outcome without debiting or granting again. A FAILED purchase claims
406
+ -- nothing, so retrying after a refusal still works. Max 64 bytes, valid UTF-8.
407
+ IdempotencyKey: string?,
408
+ -- A paid random item: refused for a player whose policy restricts them.
409
+ PaidRandom: boolean?,
410
+ }
411
+
412
+ export type PurchaseFilter = {
413
+ Kind: ("Robux" | "InGame")?,
414
+ Category: string?,
415
+ ItemId: string?,
416
+ Since: number?,
417
+ Limit: number?,
418
+ }
419
+
420
+ -- Economy analytics -----------------------------------------------------------
421
+
422
+ -- The tag passed to Increment/Decrement to auto-emit LogEconomyEvent. All
423
+ -- fields are optional: an untagged Increment writes the value without emitting.
424
+ export type EconomyMeta = {
425
+ Flow: ("Source" | "Sink")?, -- default: Increment -> Source, Decrement -> Sink
426
+ TransactionType: (Enum.AnalyticsEconomyTransactionType | string)?, -- default "Gameplay"; an EnumItem's .Name is used
427
+ ItemSku: string?,
428
+ Currency: string?, -- override the logged currency label (default: the field's name)
429
+ Fields: { [string]: any }?, -- per-event custom-field values, keyed by declared field name
430
+ -- Accepted aliases for the pre-1.1 tag shape.
431
+ Source: string?, -- alias of TransactionType
432
+ Item: string?, -- alias of ItemSku
433
+ }
434
+
435
+ -- One declared custom-field slot: a plain name (uses the currency/global Prefix
436
+ -- default) or a name with its own Prefix override.
437
+ export type EconomyFieldSpec = string | { Name: string, Prefix: boolean? }
438
+
439
+ export type EconomyCurrencyConfig = {
440
+ Label: string?, -- logged currency name (default: the field's name)
441
+ Fields: { EconomyFieldSpec }?, -- up to 3 dimensions -> CustomField01/02/03, in order
442
+ Resolve: ((player: Player) -> { [string]: any })?, -- ambient values for THIS currency, merged over the global Resolve
443
+ }
444
+
445
+ -- The seam Analytics.Economy calls; defaults to AnalyticsService:LogEconomyEvent.
446
+ -- Override it (e.g. in tests) to capture emitted events.
447
+ export type EconomyLogFn = (
448
+ player: Player,
449
+ flowType: Enum.AnalyticsEconomyFlowType,
450
+ currencyType: string,
451
+ amount: number,
452
+ endingBalance: number,
453
+ transactionType: string,
454
+ itemSku: string?,
455
+ customFields: { [string]: any }?
456
+ ) -> ()
457
+
458
+ export type EconomyConfig = {
459
+ Resolve: ((player: Player) -> { [string]: any })?, -- ambient values shared across every currency
460
+ Prefix: boolean?, -- format custom-field values as "Team - Red" (default true)
461
+ Currencies: { [string]: EconomyCurrencyConfig }?,
462
+ LogEconomyEvent: EconomyLogFn?, -- advanced/test seam; defaults to AnalyticsService:LogEconomyEvent
463
+ }
464
+
465
+ export type Disconnect = () -> ()
466
+
467
+ -- The marker Client.Request appends to every refusal that is Scribe's rather than a
468
+ -- handler's. Declared here so both realms share one identity: src/init.luau
469
+ -- re-exports it as Scribe.RequestFailed, and src/Client/init.luau returns this exact
470
+ -- table.
471
+ --
472
+ -- Identity rather than a string is the mechanism: Wire.EncodeGeneric serialises
473
+ -- tables by value and has no representation for a reference, so nothing a handler
474
+ -- returns can decode to this table, where a boolean or a string in the same slot
475
+ -- would be forgeable in one line of game code. Frozen because it is a module
476
+ -- singleton shared by every bundle in the process.
477
+ local RequestFailed = table.freeze({})
478
+
479
+ -- This module is otherwise types only; RequestFailed is the one runtime value.
480
+ return { RequestFailed = RequestFailed }