@rbxts/zyntex-sdk 1.0.2 → 6.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 delucted
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 delucted
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,6 @@
-# zyntex-sdk
-The Roblox Zyntex SDK.
-
-Types may not be complete, I am adding them as I use them.
-
-# Download
-To download the SDK, please follow the instructions in the Zyntex documentation:
-https://docs.zyntex.dev/download
+# zyntex-sdk
+The Roblox Zyntex SDK.
+
+# Download
+To download the SDK, please follow the instructions in the Zyntex documentation:
+https://docs.zyntex.dev/download

package/package.json

@@ -1,11 +1,29 @@
-{
-  "name": "@rbxts/zyntex-sdk",
-  "version": "1.0.2",
-  "description": "Typescript types for: The Roblox Zyntex SDK.",
-  "main": "init.lua",
-  "license": "MIT",
-  "types": "index.d.ts",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@rbxts/zyntex-sdk",
+  "version": "6.0.0",
+  "description": "Typescript types for: The Roblox Zyntex SDK.",
+  "main": "src/init.lua",
+  "scripts": {
+    "build": "rbxtsc",
+    "watch": "rbxtsc -w"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "types": "src/index.d.ts",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "^3.0.0-types.0",
+    "@rbxts/types": "^1.0.867",
+    "@typescript-eslint/eslint-plugin": "^8.38.0",
+    "@typescript-eslint/parser": "^8.38.0",
+    "eslint": "^9.32.0",
+    "eslint-plugin-roblox-ts": "^1.0.0",
+    "roblox-ts": "^3.0.0",
+    "typescript": "^5.8.3"
+  }
+}

package/src/Experiments.luau

@@ -0,0 +1,114 @@
+local Session = require(script.Parent:WaitForChild("api"))
+
+local Experiment = {}
+Experiment.__index = Experiment
+
+-- Represents an experiment instance
+type ExperimentType = {
+	id: string; -- The unique ID of the experiment (e.g., "new_shop_ui").
+	_session: Session.Session; -- Reference to the main Zyntex session.
+}
+
+export type Experiment = typeof(setmetatable({} :: ExperimentType, Experiment))
+
+local Group = {}
+Group.__index = Group
+
+-- Represents a group instance
+type GroupType = {
+	id: string; -- The unique ID of the group (e.g., "group_a").
+	playerId: number; -- The ID of the player that is in this group
+	_experiment: Experiment;
+}
+
+export type Group = typeof(setmetatable({} :: GroupType, Group))
+
+--[[
+	@function Group:Convert
+	@description Registers a conversion for that player in the group.
+	@param value number? -- The value this conversion provided. For example: total robux spent, time spent completing tutorial
+]]
+function Group.Convert(self: Group, value: number?)
+	self._experiment._session:post(`/experiments/{self._experiment.id}`, {
+		value = value or 0;
+		group_id = self.id;
+		player_id = self.playerId;
+	},
+		true
+	)
+end
+
+--[[
+	@constructor Group.new
+	@description Constructs a new Group object.
+	@param session Session -- Reference to the main client (for API calls).
+	@param id string -- Group ID as defined in the dashboard.
+	@return Group
+]]
+function Group.new(Experiment: Experiment, id: string, playerId: number)
+	local self = {}
+	self.id = id
+	self.playerId = playerId
+	self._experiment = Experiment
+	
+	return setmetatable(self, Group)
+end
+
+--[[
+	@constructor Experiment.new
+	@description Constructs a new Experiment object.
+	@param session Session -- Reference to the main client (for API calls).
+	@param id string -- Experiment ID as defined in the dashboard.
+	@return Experiment
+]]
+function Experiment.new(session: Session.Session, id: string): Experiment?
+	local self = {}
+	self._session = session
+	self.id = id
+	
+	local manifest = session:get(`/experiments/{id}/manifest`)
+	
+	if not manifest.success then
+		if manifest.statusCode == 404 then
+			return nil
+		end
+		
+		error(`Error when fetching experiment {id}: {manifest.user_message}`)
+	end
+	
+	return setmetatable(self, Experiment)
+end
+
+--[[
+	@function GetStatus
+	@description Fetches the current status of the experiment.
+	@return Experiment
+]]
+function Experiment.GetStatus(self: Experiment): "active" | "paused" | "archived"
+	local res = self._session:get(`/experiments/{self.id}/manifest`)
+	
+	if not res.succeess then
+		error(`Failure when fetching experiment {self.id} status: {res.user_message}`)
+	end
+	
+	return res.data.status
+end
+
+--[[
+	@function GetGroup
+	@description Registers an entry and server assigns player a group.  
+	@param playerId Player | number -- The Player to register, as a Player object or number (userId)
+	@return string
+]]
+function Experiment.GetGroup(self: Experiment, player: Player | number): Group
+	local playerId = if type(player) == "number" then player else player.UserId
+	local res = self._session:get(`/experiments/{self.id}/group/{playerId}`)
+	
+	if not res.success then
+		error(`Failure fetching group for player {playerId}: {res.user_message}`)
+	end
+	
+	return Group.new(self, res.data, playerId)
+end
+
+return Experiment

package/src/MainModule.luau

@@ -0,0 +1,23 @@
+local Zyntex = require(script:FindFirstChild("Zyntex"))
+local Session = require(script:FindFirstChild("api"))
+
+return setmetatable({}, {
+	--[[
+		Gets the current version of this module.
+	]]
+	__index = function(self, index)
+		if string.lower(index) == "version" then
+			return Zyntex.VERSION
+		end
+		if string.lower(index) == "isZyntex" then --// Important for the Zyntex upgrader plugin. When it searches for the module, make sure it has this.
+			return true
+		end
+	end,
+	--[[
+		Returns a new Zyntex object.
+		https://docs.zyntex.dev
+	]]
+	__call = function(self, gameToken: string): Zyntex.Zyntex
+		return Zyntex.new(gameToken)
+	end,
+})

package/{Telemetry.luau → src/Telemetry.luau}

@@ -1,176 +1,176 @@
-local Session = require(script.Parent:WaitForChild("api"))
-local HttpService = game:GetService("HttpService")
-
-local Telemetry = {}
-Telemetry.__index = Telemetry
-
-export type LabelSet = { [string]: string }
-
-export type MetricOpts = {
-	--[[
-	Optional human-readable description
-	]]
-	description: string?,
-	--[[
-	Labels, used for filtering metrics on the dashboard
-	]]
-	labels: { string }?,
-	--[[
-	Only for Histogram
-	]]
-	buckets: { number }?,
-}
-
-export type CounterMetric = {
-	inc: (self: CounterMetric, delta: number?, labels: LabelSet?) -> (),
-}
-
-export type GaugeMetric = {
-	set: (self: GaugeMetric, value: number,  labels: LabelSet?) -> (),
-	inc: (self: GaugeMetric, delta: number?, labels: LabelSet?) -> (),
-	dec: (self: GaugeMetric, delta: number?, labels: LabelSet?) -> (),
-}
-
-export type HistogramMetric = {
-	observe: (self: HistogramMetric, value: number, labels: LabelSet?) -> (),
-}
-
-export type SummaryMetric = {
-	observe: (self: SummaryMetric, value: number, labels: LabelSet?) -> (),
-}
-
-function Telemetry.new(registryName: string?, flushEvery: number?, session: Session.Session)
-	return setmetatable({
-		_name           = registryName or "default",
-		_buffer         = {},           -- pending samples
-		_flushEvery     = flushEvery or 10,
-		_lastFlush      = os.clock(),
-		_session        = session
-	}, Telemetry)
-end
-
---[[
-	Generic pushSample shared by all metric types
-]]
-local function pushSample(self, kind: string, name: string, value, labels: LabelSet)
-	table.insert(self._buffer, {
-		t  = os.time(), -- UTC seconds
-		k  = kind,      -- counter | gauge | hist | sum
-		n  = name,      -- metric name
-		v  = value,     -- number or bucket-map
-		l  = labels     -- table<string,string>
-	})
-
-	if os.clock() - self._lastFlush >= self._flushEvery then
-		self:flush()
-	end
-end
-
-function Telemetry:flush()
-	if #self._buffer == 0 then return end
-	pcall(function()
-		self._session:post(
-			"/telemetry/push",
-			{buffer = self._buffer}
-		)
-	end)
-	self._buffer, self._lastFlush = {}, os.clock()
-end
-
---[[
-	Creates (or fetches) a monotonically increasing **counter** metric.
-
-	@param self  Telemetry         – the registry instance.
-	@param name  string            – metric name (snake_case).
-	@param opts  MetricOpts?       – optional descriptor & label schema.
-
-	@return CounterMetric handle   – call `:inc()` to push samples.
-
-	Example
-	```lua
-	local shots = registry:Counter("weapon_shots_total", {
-		description = "Number of shots fired per weapon",
-		labels      = {"weapon"}
-	})
-
-	shots:inc()                    -- +1
-	shots:inc(3, {weapon="AK-47"}) -- +3 with a label
-	```
-]]--
-function Telemetry:Counter(name: string, opts: MetricOpts?): CounterMetric
-	local total = 0
-	return ({
-		inc = function(_: CounterMetric, delta: number?, lbls: LabelSet?)
-			total += delta or 1
-			pushSample(self, "counter", name, total, lbls or {})
-		end,
-	} :: any) :: CounterMetric
-end
-
---[[
-	Creates a **gauge** metric – an instantaneous value that can go up
-	or down (e.g. memory, player count, FPS).
-
-	`set()` overrides the value directly, while `inc()` / `dec()` apply
-	deltas.
-
-	@return GaugeMetric handle.
-]]--
-function Telemetry:Gauge(name: string, opts: MetricOpts?): GaugeMetric
-	return ({
-
-		set = function(_: GaugeMetric, value: number, lbls: LabelSet?)
-			pushSample(self, "gauge", name, value, lbls or {})
-		end,
-
-		inc = function(_: GaugeMetric, delta: number?, lbls: LabelSet?)
-			pushSample(self, "gauge", name,  delta or 1, lbls or {})
-		end,
-
-		dec = function(_: GaugeMetric, delta: number?, lbls: LabelSet?)
-			pushSample(self, "gauge", name, -(delta or 1), lbls or {})
-		end,
-
-	} :: any) :: GaugeMetric
-end
-
---[[
-	Creates a **histogram** metric – captures a distribution of values
-	(e.g. damage dealt, ping). `buckets` may be provided in `opts`.
-
-	The raw sample value is sent unchanged; bucketing happens on the
-	back-end so bucket definitions can evolve without client updates.
-
-	@return HistogramMetric handle.
-]]--
-function Telemetry:Histogram(name: string, opts: MetricOpts?): HistogramMetric
-	local buckets: {number}? = opts and opts.buckets
-	return ({
-
-		observe = function(_: HistogramMetric, value: number, lbls: LabelSet?)
-			local combined: LabelSet = lbls and table.clone(lbls) or {}
-			if buckets then combined._buckets = HttpService:JSONEncode(buckets) end
-			pushSample(self, "hist", name, value, combined)
-		end,
-
-	} :: any) :: HistogramMetric
-end
-
---[[
-	Creates a **summary** metric – similar to histogram but intended
-	for quantile estimation (P-style summaries). Uses a single `observe`
-	method.
-
-	@return SummaryMetric handle.
-]]--
-function Telemetry:Summary(name: string, opts: MetricOpts?): SummaryMetric
-	return ({
-
-		observe = function(_: SummaryMetric, value: number, lbls: LabelSet?)
-			pushSample(self, "sum", name, value, lbls or {})
-		end,
-
-	} :: any) :: SummaryMetric
-end
-
-return Telemetry
+local Session = require(script.Parent:WaitForChild("api"))
+local HttpService = game:GetService("HttpService")
+
+local Telemetry = {}
+Telemetry.__index = Telemetry
+
+export type LabelSet = { [string]: string }
+
+export type MetricOpts = {
+	--[[
+	Optional human-readable description
+	]]
+	description: string?,
+	--[[
+	Labels, used for filtering metrics on the dashboard
+	]]
+	labels: { string }?,
+	--[[
+	Only for Histogram
+	]]
+	buckets: { number }?,
+}
+
+export type CounterMetric = {
+	inc: (self: CounterMetric, delta: number?, labels: LabelSet?) -> (),
+}
+
+export type GaugeMetric = {
+	set: (self: GaugeMetric, value: number,  labels: LabelSet?) -> (),
+	inc: (self: GaugeMetric, delta: number?, labels: LabelSet?) -> (),
+	dec: (self: GaugeMetric, delta: number?, labels: LabelSet?) -> (),
+}
+
+export type HistogramMetric = {
+	observe: (self: HistogramMetric, value: number, labels: LabelSet?) -> (),
+}
+
+export type SummaryMetric = {
+	observe: (self: SummaryMetric, value: number, labels: LabelSet?) -> (),
+}
+
+function Telemetry.new(registryName: string?, flushEvery: number?, session: Session.Session)
+	return setmetatable({
+		_name           = registryName or "default",
+		_buffer         = {},           -- pending samples
+		_flushEvery     = flushEvery or 10,
+		_lastFlush      = os.clock(),
+		_session        = session
+	}, Telemetry)
+end
+
+--[[
+	Generic pushSample shared by all metric types
+]]
+local function pushSample(self, kind: string, name: string, value, labels: LabelSet)
+	table.insert(self._buffer, {
+		t  = os.time(), -- UTC seconds
+		k  = kind,      -- counter | gauge | hist | sum
+		n  = name,      -- metric name
+		v  = value,     -- number or bucket-map
+		l  = labels     -- table<string,string>
+	})
+
+	if os.clock() - self._lastFlush >= self._flushEvery then
+		self:flush()
+	end
+end
+
+function Telemetry:flush()
+	if #self._buffer == 0 then return end
+	pcall(function()
+		self._session:post(
+			"/telemetry/push",
+			{buffer = self._buffer}
+		)
+	end)
+	self._buffer, self._lastFlush = {}, os.clock()
+end
+
+--[[
+	Creates (or fetches) a monotonically increasing **counter** metric.
+
+	@param self  Telemetry         – the registry instance.
+	@param name  string            – metric name (snake_case).
+	@param opts  MetricOpts?       – optional descriptor & label schema.
+
+	@return CounterMetric handle   – call `:inc()` to push samples.
+
+	Example
+	```lua
+	local shots = registry:Counter("weapon_shots_total", {
+		description = "Number of shots fired per weapon",
+		labels      = {"weapon"}
+	})
+
+	shots:inc()                    -- +1
+	shots:inc(3, {weapon="AK-47"}) -- +3 with a label
+	```
+]]--
+function Telemetry:Counter(name: string, opts: MetricOpts?): CounterMetric
+	local total = 0
+	return ({
+		inc = function(_: CounterMetric, delta: number?, lbls: LabelSet?)
+			total += delta or 1
+			pushSample(self, "counter", name, total, lbls or {})
+		end,
+	} :: any) :: CounterMetric
+end
+
+--[[
+	Creates a **gauge** metric – an instantaneous value that can go up
+	or down (e.g. memory, player count, FPS).
+
+	`set()` overrides the value directly, while `inc()` / `dec()` apply
+	deltas.
+
+	@return GaugeMetric handle.
+]]--
+function Telemetry:Gauge(name: string, opts: MetricOpts?): GaugeMetric
+	return ({
+
+		set = function(_: GaugeMetric, value: number, lbls: LabelSet?)
+			pushSample(self, "gauge", name, value, lbls or {})
+		end,
+
+		inc = function(_: GaugeMetric, delta: number?, lbls: LabelSet?)
+			pushSample(self, "gauge", name,  delta or 1, lbls or {})
+		end,
+
+		dec = function(_: GaugeMetric, delta: number?, lbls: LabelSet?)
+			pushSample(self, "gauge", name, -(delta or 1), lbls or {})
+		end,
+
+	} :: any) :: GaugeMetric
+end
+
+--[[
+	Creates a **histogram** metric – captures a distribution of values
+	(e.g. damage dealt, ping). `buckets` may be provided in `opts`.
+
+	The raw sample value is sent unchanged; bucketing happens on the
+	back-end so bucket definitions can evolve without client updates.
+
+	@return HistogramMetric handle.
+]]--
+function Telemetry:Histogram(name: string, opts: MetricOpts?): HistogramMetric
+	local buckets: {number}? = opts and opts.buckets
+	return ({
+
+		observe = function(_: HistogramMetric, value: number, lbls: LabelSet?)
+			local combined: LabelSet = lbls and table.clone(lbls) or {}
+			if buckets then combined._buckets = HttpService:JSONEncode(buckets) end
+			pushSample(self, "hist", name, value, combined)
+		end,
+
+	} :: any) :: HistogramMetric
+end
+
+--[[
+	Creates a **summary** metric – similar to histogram but intended
+	for quantile estimation (P-style summaries). Uses a single `observe`
+	method.
+
+	@return SummaryMetric handle.
+]]--
+function Telemetry:Summary(name: string, opts: MetricOpts?): SummaryMetric
+	return ({
+
+		observe = function(_: SummaryMetric, value: number, lbls: LabelSet?)
+			pushSample(self, "sum", name, value, lbls or {})
+		end,
+
+	} :: any) :: SummaryMetric
+end
+
+return Telemetry