@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
@@ -0,0 +1,223 @@
1
+ --!strict
2
+ -- Economy source/sink analytics. Currency mutations tagged via Increment/Decrement (and
3
+ -- Data.Purchase) auto-emit AnalyticsService:LogEconomyEvent, with the currency taken from
4
+ -- the mutated field's name. Custom fields, an ambient Resolve and a label override are
5
+ -- declared once in options.Economy. Failures log at Debug and never block gameplay.
6
+
7
+ local AnalyticsService = game:GetService("AnalyticsService")
8
+
9
+ local Internal = script.Parent.Parent.Internal
10
+ local Log = require(Internal.Log)
11
+ local Metrics = require(Internal.Metrics)
12
+ local Types = require(script.Parent.Parent.Types)
13
+
14
+ local Analytics = {}
15
+
16
+ -- Roblox exposes exactly three economy custom-field slots.
17
+ local MAX_FIELDS = 3
18
+
19
+ -- Resolve a transaction type from the tag: an Enum.AnalyticsEconomyTransactionType
20
+ -- (a real EnumItem, or the headless test fake, which is a table carrying .Name),
21
+ -- a plain string, or nil -> "Gameplay".
22
+ local function txnName(value: any): string
23
+ if value == nil then
24
+ return "Gameplay"
25
+ end
26
+ if typeof(value) == "EnumItem" then
27
+ return (value :: EnumItem).Name
28
+ end
29
+ if type(value) == "table" and type((value :: any).Name) == "string" then
30
+ return (value :: any).Name
31
+ end
32
+ return tostring(value)
33
+ end
34
+
35
+ type FieldSpec = { Name: string, Prefix: boolean }
36
+ type Currency = {
37
+ Label: string?,
38
+ Resolve: ((player: Player) -> { [string]: any })?,
39
+ Fields: { FieldSpec },
40
+ Declared: { [string]: boolean },
41
+ }
42
+
43
+ function Analytics.new(ctx: any)
44
+ local self = {} :: any
45
+ local options = ctx.Options or {}
46
+ local economy = options.Economy or {}
47
+ local devMode: boolean = ctx.DevMode == true
48
+
49
+ -- Cast the (any-typed) override to the seam's function type so the default
50
+ -- and the call site below are both concretely callable, not `~(false?)`.
51
+ local logEconomy = (economy.LogEconomyEvent :: Types.EconomyLogFn?)
52
+ or function(
53
+ player: Player,
54
+ flowType: Enum.AnalyticsEconomyFlowType,
55
+ currency: string,
56
+ amount: number,
57
+ balance: number,
58
+ transactionType: string,
59
+ itemSku: string?,
60
+ customFields: { [string]: any }?
61
+ )
62
+ AnalyticsService:LogEconomyEvent(
63
+ player,
64
+ flowType,
65
+ currency,
66
+ amount,
67
+ balance,
68
+ transactionType,
69
+ itemSku,
70
+ customFields
71
+ )
72
+ end
73
+
74
+ local defaultPrefix: boolean = economy.Prefix ~= false -- default true
75
+ local globalResolve = economy.Resolve
76
+
77
+ -- CustomField01/02/03 key names (the strings LogEconomyEvent expects).
78
+ local slotKeys: { string } = {}
79
+ for i = 1, MAX_FIELDS do
80
+ slotKeys[i] = (Enum.AnalyticsCustomFieldKeys :: any)[string.format("CustomField%02d", i)].Name
81
+ end
82
+
83
+ -- Precompile each currency's ordered slot specs (capped at the Roblox slots), a
84
+ -- declared-name set for typo warnings, and its label and resolver overrides.
85
+ local currencies: { [string]: Currency } = {}
86
+ for name, raw in (economy.Currencies or {}) :: { [string]: any } do
87
+ local fields: { FieldSpec } = {}
88
+ local declared: { [string]: boolean } = {}
89
+ for _, spec in (raw.Fields or {}) :: { any } do
90
+ local fieldName: any
91
+ local fieldPrefix: boolean
92
+ if type(spec) == "table" then
93
+ fieldName = spec.Name
94
+ fieldPrefix = if spec.Prefix == nil then defaultPrefix else spec.Prefix == true
95
+ else
96
+ fieldName = spec
97
+ fieldPrefix = defaultPrefix
98
+ end
99
+ if type(fieldName) ~= "string" then
100
+ error(
101
+ `Scribe: Economy.Currencies["{name}"].Fields entries must be a field name or \{ Name = "..." }`,
102
+ 0
103
+ )
104
+ end
105
+ declared[fieldName] = true
106
+ if #fields >= MAX_FIELDS then
107
+ -- Silent truncation would read as "recorded" when it wasn't.
108
+ if devMode then
109
+ Log.Warn(
110
+ "Integrity",
111
+ "ECONOMY_FIELDS_OVERFLOW",
112
+ `currency "{name}" declares more than {MAX_FIELDS} custom fields; "{fieldName}" and any beyond it are dropped (Roblox allows {MAX_FIELDS})`,
113
+ { Currency = name, Field = fieldName }
114
+ )
115
+ end
116
+ else
117
+ table.insert(fields, { Name = fieldName, Prefix = fieldPrefix })
118
+ end
119
+ end
120
+ currencies[name] = { Label = raw.Label, Resolve = raw.Resolve, Fields = fields, Declared = declared }
121
+ end
122
+
123
+ -- Merge a resolver's output into the pool, fail-safe: a throwing resolver
124
+ -- drops its fields (logged at Debug) rather than losing the whole event.
125
+ local function resolveInto(pool: { [string]: any }, fn: any, player: Player)
126
+ if not fn then
127
+ return
128
+ end
129
+ local ok, res = pcall(fn, player)
130
+ if ok and type(res) == "table" then
131
+ for key, value in res do
132
+ pool[key] = value
133
+ end
134
+ elseif not ok then
135
+ Log.Debug("Integrity", "ANALYTICS_FAIL", `economy Resolve threw: {tostring(res)}`, { Player = player })
136
+ end
137
+ end
138
+
139
+ local function buildCustomFields(player: Player, currency: Currency?, tags: { [string]: any }): { [string]: any }?
140
+ -- Custom fields need a declared slot mapping; an undeclared currency, or one with
141
+ -- no Fields, logs a plain event.
142
+ if not currency or #currency.Fields == 0 then
143
+ return nil
144
+ end
145
+ local pool: { [string]: any } = {}
146
+ resolveInto(pool, globalResolve, player)
147
+ resolveInto(pool, currency.Resolve, player)
148
+ local perCall = tags.Fields
149
+ if type(perCall) == "table" then
150
+ for key, value in perCall do
151
+ pool[key] = value
152
+ if devMode and not currency.Declared[key] then
153
+ Log.Warn(
154
+ "Integrity",
155
+ "ECONOMY_FIELD_UNDECLARED",
156
+ `economy field "{key}" is not declared for this currency and will not be recorded (typo?)`,
157
+ { Player = player, Field = key }
158
+ )
159
+ end
160
+ end
161
+ end
162
+ local out: { [string]: any } = {}
163
+ local any = false
164
+ for i, spec in currency.Fields do
165
+ local value = pool[spec.Name]
166
+ if value ~= nil then
167
+ out[slotKeys[i]] = if spec.Prefix then `{spec.Name} - {value}` else value
168
+ any = true
169
+ end
170
+ end
171
+ return if any then out else nil
172
+ end
173
+
174
+ function self.Economy(
175
+ player: Player,
176
+ path: { string | number },
177
+ delta: number,
178
+ newValue: number,
179
+ tags: { [string]: any }
180
+ )
181
+ local fieldName = tostring(path[#path]) -- internal path segment; always safe
182
+ local currency = currencies[fieldName]
183
+ local flowType = if tags.Flow == "Sink"
184
+ then Enum.AnalyticsEconomyFlowType.Sink
185
+ else Enum.AnalyticsEconomyFlowType.Source
186
+ -- Safe fallback so the failure log below always has a label, even when the
187
+ -- caller-supplied Currency is the value that threw.
188
+ local currencyLabel = fieldName
189
+
190
+ -- One guard around formatting, field building and the log: every value here is
191
+ -- caller-supplied, and a throwing `__tostring` or `__iter` must not escape into
192
+ -- the Increment/Decrement caller after the write already applied.
193
+ local ok, err = pcall(function()
194
+ currencyLabel = tostring(tags.Currency or (currency and currency.Label) or fieldName)
195
+ local transactionType = txnName(if tags.TransactionType ~= nil then tags.TransactionType else tags.Source)
196
+ local itemSkuRaw = if tags.ItemSku ~= nil then tags.ItemSku else tags.Item
197
+ local itemSku = if itemSkuRaw ~= nil then tostring(itemSkuRaw) else nil
198
+ local customFields = buildCustomFields(player, currency, tags)
199
+ logEconomy(
200
+ player,
201
+ flowType,
202
+ currencyLabel,
203
+ math.abs(delta),
204
+ newValue,
205
+ transactionType,
206
+ itemSku,
207
+ customFields
208
+ )
209
+ end)
210
+ if ok then
211
+ Metrics.Add("EconomyEvents") -- count successes, not attempts
212
+ else
213
+ -- Debug logs are suppressed in production, so the counter is what makes a
214
+ -- systematically failing pipeline visible.
215
+ Metrics.Add("EconomyEventFailures")
216
+ Log.Debug("Integrity", "ANALYTICS_FAIL", tostring(err), { Player = player, Currency = currencyLabel })
217
+ end
218
+ end
219
+
220
+ return self
221
+ end
222
+
223
+ return Analytics