From e4fa158e8e27345d1dc8df3410da5b616b4e29fc Mon Sep 17 00:00:00 2001
From: filoxenace <duskhop@gmail.com>
Date: Mon, 16 Feb 2026 17:58:06 -0500
Subject: [PATCH] v0.1.1: add configure() method, wally dependency, project
 config

---
 README.md     | 27 ++++++++++++++++++++++++++-
 src/init.luau | 22 +++++++++++++++-------
 wally.toml    |  2 +-
 3 files changed, 42 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index b7e5d3a..b1ea8a5 100644
--- a/README.md
+++ b/README.md
@@ -17,5 +17,30 @@ 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.
+1. Add your Filoxen API key as a secret in the [Creator Dashboard](https://create.roblox.com) under Secrets (defaults to `FILOXEN_API_KEY`).
 2. Make sure `HttpService` is enabled for your game.
+
+## Usage
+
+```luau
+local Filoxen = require(path.to.Filoxen)
+
+-- Must be called once before any other function
+Filoxen.configure({
+    baseUrl = "https://your-filoxen-instance.com",
+    apiKeySecretName = "FILOXEN_API_KEY", -- optional, this is the default
+})
+
+-- Fetch 10 random hats
+local assets = Filoxen.random(
+    { Enum.AssetType.Hat },  -- assetTypeIds
+    nil,                     -- maxAssetId
+    nil,                     -- minAssetId
+    10,                      -- batch
+    true                     -- onsale
+)
+
+-- Search for assets by name
+local results = Filoxen.search("blue hat", Enum.AssetType.Hat.Value)
+```
+
diff --git a/src/init.luau b/src/init.luau
index 9cbecbf..1499924 100644
--- a/src/init.luau
+++ b/src/init.luau
@@ -4,15 +4,23 @@ 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 BASE_URL: string? = nil
+local API_KEY: Secret? = nil
 
-local API_KEY = HttpService:GetSecret(API_KEY_SECRET_NAME)
+export type Config = {
+	baseUrl: string,
+	apiKeySecretName: string?,
+}
+
+function module.configure(config: Config)
+	BASE_URL = config.baseUrl
+	local secretName = config.apiKeySecretName or "FILOXEN_API_KEY"
+	API_KEY = HttpService:GetSecret(secretName)
+end
 
 -- Makes a GET request to the Filoxen API and decodes the assets array from the response.
 local function makeApiRequest(url: string): {Types.Asset}?
+	assert(BASE_URL and API_KEY, "[Filoxen] Must call .configure() before using the API")
 	local success, response = pcall(function()
 		return HttpService:RequestAsync({
 			Url = url,
@@ -43,7 +51,7 @@ 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}`
+	local REQUEST_URL = `{BASE_URL}/assets/random?assetTypeIds={table.concat(assetTypeIds, ',')}&batch={batch}`
 	if type(onsale) == "boolean" then
 		onsale = if onsale then 1 else 0
 	end
@@ -70,7 +78,7 @@ 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}`
+	local REQUEST_URL = `{BASE_URL}/assets/search?assetTypeId={assetTypeId}&query={HttpService:UrlEncode(query)}&page={page}`
 	return makeApiRequest(REQUEST_URL)
 end
 
diff --git a/wally.toml b/wally.toml
index 135fef7..8e6d91e 100644
--- a/wally.toml
+++ b/wally.toml
@@ -1,6 +1,6 @@
 [package]
 name = "secret-rare/filoxen-luau"
-version = "0.1.0"
+version = "0.1.1"
 registry = "https://github.com/UpliftGames/wally-index"
 realm = "server"