From f1a97a923b9e8868284ae4b3f878760b8a99fa0d Mon Sep 17 00:00:00 2001
From: filoxenace <duskhop@gmail.com>
Date: Mon, 16 Feb 2026 17:50:33 -0500
Subject: [PATCH] Initial commit

---
 .gitignore           |  2 ++
 README.md            | 21 ++++++++++++
 default.project.json |  9 ++++++
 rokit.toml           |  7 ++++
 src/init.luau        | 77 ++++++++++++++++++++++++++++++++++++++++++++
 wally.toml           |  8 +++++
 6 files changed, 124 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 default.project.json
 create mode 100644 rokit.toml
 create mode 100644 src/init.luau
 create mode 100644 wally.toml

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..04387be
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+Packages/
+wally.lock
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b7e5d3a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,21 @@
+# filoxen-luau
+
+Luau client library for the Filoxen asset API. Fetch random or search for Roblox assets.
+
+## Installation
+
+Requires [Wally](https://wally.run).
+
+```toml
+[dependencies]
+Filoxen = "secret-rare/filoxen-luau@0.1.0"
+```
+
+```sh
+wally install
+```
+
+## Setup
+
+1. Add your Filoxen API key as a secret named `FILOXEN_API_KEY` in the [Creator Dashboard](https://create.roblox.com) under Secrets.
+2. Make sure `HttpService` is enabled for your game.
diff --git a/default.project.json b/default.project.json
new file mode 100644
index 0000000..83de415
--- /dev/null
+++ b/default.project.json
@@ -0,0 +1,9 @@
+{
+	"name": "filoxen-luau",
+	"tree": {
+		"$path": "src",
+		"Packages": {
+			"$path": "Packages"
+		}
+	}
+}
diff --git a/rokit.toml b/rokit.toml
new file mode 100644
index 0000000..654bc45
--- /dev/null
+++ b/rokit.toml
@@ -0,0 +1,7 @@
+# This file lists tools managed by Rokit, a toolchain manager for Roblox projects.
+# For more information, see https://github.com/rojo-rbx/rokit
+
+# New tools can be added by running `rokit add <tool>` in a terminal.
+
+[tools]
+wally = "UpliftGames/wally@0.3.2"
diff --git a/src/init.luau b/src/init.luau
new file mode 100644
index 0000000..9cbecbf
--- /dev/null
+++ b/src/init.luau
@@ -0,0 +1,77 @@
+local module = {}
+
+local HttpService = game:GetService("HttpService")
+local RbxAssetUtils = require(script.Packages.RbxAssetUtils)
+local Types = RbxAssetUtils.Types
+
+-- Change this to your own API instance URL if self-hosting.
+local API_URL_BASE = "https://filoxen.example.com"
+-- Name of the secret in the Secrets Store (Creator Dashboard -> Secrets).
+local API_KEY_SECRET_NAME = "FILOXEN_API_KEY"
+
+local API_KEY = HttpService:GetSecret(API_KEY_SECRET_NAME)
+
+-- Makes a GET request to the Filoxen API and decodes the assets array from the response.
+local function makeApiRequest(url: string): {Types.Asset}?
+	local success, response = pcall(function()
+		return HttpService:RequestAsync({
+			Url = url,
+			Method = "GET",
+			Headers = {
+				["x-api-key"] = API_KEY
+			}
+		})
+	end)
+	if success and response.Success then
+		local decodeSuccess, responseData = pcall(HttpService.JSONDecode, HttpService, response.Body)
+		if not decodeSuccess then
+			warn(`[Filoxen] API response decode failed: {tostring(responseData)}`)
+			return {}
+		end
+		local assets: {Types.Asset}? = responseData["assets"]
+		if not assets then
+			warn("[Filoxen] API response missing 'assets' field")
+			return {}
+		end
+		return assets
+	else
+		local errorMessage = if success then `HTTP {response.StatusCode}: {response.StatusMessage}` else tostring(response)
+		warn(`[Filoxen] API request failed: {errorMessage}`)
+		return {}
+	end
+end
+
+-- Fetches random assets from the Filoxen API with the given filters.
+function module.random(assetTypeIds: {number | Enum.AssetType}, maxAssetId: number?, minAssetId: number?, batch: number, onsale: number | boolean?, playable: number?): {Types.Asset}?
+	local REQUEST_URL = `{API_URL_BASE}/assets/random?assetTypeIds={table.concat(assetTypeIds, ',')}&batch={batch}`
+	if type(onsale) == "boolean" then
+		onsale = if onsale then 1 else 0
+	end
+	for i, assetTypeId in ipairs(assetTypeIds) do
+		if typeof(assetTypeId) == "EnumItem" then
+			assetTypeIds[i] = assetTypeId.Value
+		end
+	end
+	if maxAssetId then
+		REQUEST_URL = `{REQUEST_URL}&maxAssetId={maxAssetId}`
+	end
+	if minAssetId then
+		REQUEST_URL = `{REQUEST_URL}&minAssetId={minAssetId}`
+	end
+	if onsale then
+		REQUEST_URL = `{REQUEST_URL}&onsale={onsale}`
+	end
+	if playable then
+		REQUEST_URL = `{REQUEST_URL}&playable={playable}`
+	end
+	return makeApiRequest(REQUEST_URL)
+end
+
+-- Searches for assets matching a query string via the Filoxen API.
+function module.search(query: string, assetTypeId: number, page: number?): {Types.Asset}?
+	if not page then page = 1 end
+	local REQUEST_URL = `{API_URL_BASE}/assets/search?assetTypeId={assetTypeId}&query={HttpService:UrlEncode(query)}&page={page}`
+	return makeApiRequest(REQUEST_URL)
+end
+
+return module
diff --git a/wally.toml b/wally.toml
new file mode 100644
index 0000000..135fef7
--- /dev/null
+++ b/wally.toml
@@ -0,0 +1,8 @@
+[package]
+name = "secret-rare/filoxen-luau"
+version = "0.1.0"
+registry = "https://github.com/UpliftGames/wally-index"
+realm = "server"
+
+[dependencies]
+RbxAssetUtils = "secret-rare/rbx-asset-utils@0.1.0"