### Local Development Commands for RaiderCache

Source: https://github.com/otdavies/raidercache/blob/main/README.md

These bash commands are used to set up and run the RaiderCache project locally. They cover installing dependencies, fetching game data, starting the development server, building for production, and previewing the production build.

```bash
# Install dependencies
npm install

# Fetch game data
npm run fetch-data

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

--------------------------------

### Manual Data Fetching and Processing (TypeScript)

Source: https://context7.com/otdavies/raidercache/llms.txt

Provides example functions for manually fetching JSON data from APIs and data from Supabase within a custom script. It demonstrates how to handle paginated responses, process data into maps, and perform file format conversions, such as converting WebP images to PNG.

```typescript
// Example: Manual data fetching in custom script
import { fetchJSON, fetchSupabase } from './scripts/fetch-data';

// Fetch items with pagination
const response = await fetchJSON<MetaForgePaginatedResponse<MetaForgeItem>>(
  'https://metaforge.app/api/arc-raiders/items?page=1&limit=100'
);

// Fetch crafting components from Supabase
const components = await fetchSupabase<SupabaseComponent[]>(
  'arc_item_components',
  'select=*'
);

// Group components by item
const craftingMap = new Map<string, Record<string, number>>();
for (const component of components) {
  if (!craftingMap.has(component.item_id)) {
    craftingMap.set(component.item_id, {});
  }
  craftingMap.get(component.item_id)![component.component_id] = component.quantity;
}

// Convert WebP icon to PNG
await convertWebPToPNG(
  'https://cdn.metaforge.app/icons/item.webp',
  './public/assets/icons/item.png'
);
```

--------------------------------

### Manage Project Dependencies and Build Process

Source: https://context7.com/otdavies/raidercache/llms.txt

Provides commands for managing project dependencies, running a development server with hot module replacement, performing type checking, building for production, and previewing the production build. It also includes a command for validating data integrity.

```bash
# Install dependencies
npm install

# Start development server (Vite HMR)
npm run dev
# Serves at http://localhost:5173

# Type checking without emit
npm run type-check

# Build for production
npm run build
# 1. Compiles TypeScript (tsc)
# 2. Bundles with Vite
# 3. Outputs to dist/
# 4. Optimizes assets and code splitting

# Preview production build
npm run preview
# Serves dist/ at http://localhost:4173

# Validate data integrity
npm run validate-data
```

--------------------------------

### Access MetaForge API Endpoints

Source: https://context7.com/otdavies/raidercache/llms.txt

Demonstrates how to fetch game data from the MetaForge API, including items, quests, crafting components, recycle mappings, and map data. It also shows how to access CDN assets like map images and item icons.

```bash
# MetaForge API - Primary data source
GET https://metaforge.app/api/arc-raiders/items?page=1&limit=100
# Returns: { data: Item[], pagination: { page, total, hasNextPage } }

GET https://metaforge.app/api/arc-raiders/quests?page=1&limit=100
# Returns: { data: Quest[], pagination: { page, total, hasNextPage } }

# MetaForge Supabase - Crafting and recycle data
GET https://unhbvkszwhczbjxgetgk.supabase.co/rest/v1/arc_item_components?select=*
# Headers: apikey, Authorization (uses public anon key)
# Returns: [{ item_id, component_id, quantity, created_at, updated_at }]

GET https://unhbvkszwhczbjxgetgk.supabase.co/rest/v1/arc_item_recycle_components?select=*
# Returns recycle component mappings

GET https://unhbvkszwhczbjxgetgk.supabase.co/rest/v1/arc_map_data?map=eq.spaceport&select=*
# Returns: [{ id, subcategory, lat, lng, map, category, instance_name }]

# CDN Assets
GET https://cdn.metaforge.app/arc-raiders/ui/{mapname}.webp
# Map images

GET https://cdn.metaforge.app/arc-raiders/maps/{mapname}/v2/{z}/{x}/{y}.webp
# Map tiles (auto-discovers correct URL pattern with fallbacks)

GET https://cdn.metaforge.app/icons/{itemid}.webp
# Item icons (converted to PNG locally)
```

--------------------------------

### MetaForge Supabase - Recycle Components

Source: https://context7.com/otdavies/raidercache/llms.txt

Retrieves component mappings for item recycling from the MetaForge Supabase instance.

```APIDOC
## GET /rest/v1/arc_item_recycle_components

### Description
Fetches the component mappings for item recycling from the Supabase database.

### Method
GET

### Endpoint
`https://unhbvkszwhczbjxgetgk.supabase.co/rest/v1/arc_item_recycle_components`

### Query Parameters
- **select** (string) - Optional - Specifies which columns to retrieve. Use '*` for all columns.

### Headers
- **apikey** (string) - Required - Your Supabase API key.
- **Authorization** (string) - Required - Bearer token for authentication (uses public anon key).

### Response
#### Success Response (200)
- Returns an array of objects representing recycle component mappings.
```

--------------------------------

### Initialize and Filter Application Data

Source: https://context7.com/otdavies/raidercache/llms.txt

Configures the main application with various filtering options for items, including search queries, decisions, rarities, categories, zones, and sorting. It also demonstrates manual filter application and workshop level updates, which trigger automatic recalculations and UI re-renders.

```typescript
import { App } from './main';

// App automatically initializes on page load
// Bootstrap function handles PvP gate check before init

// Filter system supports multiple dimensions:
const filters = {
  searchQuery: 'legendary',
  decisions: new Set(['keep']),
  rarities: new Set(['legendary', 'epic']),
  categories: new Map([
    ['Weapon', 'include'],
    ['Cosmetic', 'exclude']
  ]),
  zones: ['spaceport', 'dam'],
  sortBy: 'value',
  sortDirection: 'desc'
};

// Manual filter application (normally handled by UI)
app.applyFilters();

// Workshop level updates trigger recalculation
app.updateWorkshopLevel('workshop', 3);
// Automatically:
// - Updates userProgress
// - Saves to localStorage
// - Recalculates all decisions
// - Updates search index
// - Re-renders UI

// View modes: grid (desktop default) or list (mobile default)
// Automatically switches based on screen width (768px breakpoint)
```

--------------------------------

### Automated Data Fetching Script (Bash)

Source: https://context7.com/otdavies/raidercache/llms.txt

A Node.js script designed to automate the fetching of game data and assets from various sources, including the MetaForge API and Supabase. It handles pagination, downloads various asset types like map data and images, performs format conversions, and generates metadata.

```bash
# Fetch all game data and assets
npm run fetch-data

# Script performs the following operations:
# 1. Fetches items from MetaForge API (paginated)
# 2. Fetches quests with requirements and rewards
# 3. Fetches crafting recipes from Supabase
# 4. Fetches recycle data from Supabase
# 5. Downloads map marker data for all maps
# 6. Downloads map images (WebP format)
# 7. Downloads map tiles with auto-discovery of URL patterns
# 8. Converts item icons from WebP to PNG (128px height)
# 9. Calculates map extents from tile dimensions
# 10. Generates metadata.json with timestamps
```

--------------------------------

### MetaForge API - Items

Source: https://context7.com/otdavies/raidercache/llms.txt

Fetches item data from the MetaForge API. Supports pagination for efficient data retrieval.

```APIDOC
## GET /api/arc-raiders/items

### Description
Retrieves a paginated list of items from the MetaForge API.

### Method
GET

### Endpoint
`https://metaforge.app/api/arc-raiders/items`

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **limit** (integer) - Optional - The number of items per page.

### Response
#### Success Response (200)
- **data** (array) - An array of item objects.
- **pagination** (object) - Pagination details including current page, total items, and if there's a next page.
```

--------------------------------

### MetaForge API - Quests

Source: https://context7.com/otdavies/raidercache/llms.txt

Fetches quest data from the MetaForge API. Supports pagination for efficient data retrieval.

```APIDOC
## GET /api/arc-raiders/quests

### Description
Retrieves a paginated list of quests from the MetaForge API.

### Method
GET

### Endpoint
`https://metaforge.app/api/arc-raiders/quests`

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **limit** (integer) - Optional - The number of quests per page.

### Response
#### Success Response (200)
- **data** (array) - An array of quest objects.
- **pagination** (object) - Pagination details including current page, total quests, and if there's a next page.
```

--------------------------------

### MetaForge Supabase - Item Components

Source: https://context7.com/otdavies/raidercache/llms.txt

Retrieves crafting component data for items from the MetaForge Supabase instance.

```APIDOC
## GET /rest/v1/arc_item_components

### Description
Fetches all item crafting component data from the Supabase database.

### Method
GET

### Endpoint
`https://unhbvkszwhczbjxgetgk.supabase.co/rest/v1/arc_item_components`

### Query Parameters
- **select** (string) - Optional - Specifies which columns to retrieve. Use '*` for all columns.

### Headers
- **apikey** (string) - Required - Your Supabase API key.
- **Authorization** (string) - Required - Bearer token for authentication (uses public anon key).

### Response
#### Success Response (200)
- Returns an array of objects, where each object represents an item component with fields like `item_id`, `component_id`, `quantity`, `created_at`, and `updated_at`.
```

--------------------------------

### DecisionEngine - Analyze Loot Decisions with TypeScript

Source: https://context7.com/otdavies/raidercache/llms.txt

The DecisionEngine class evaluates in-game items to determine the optimal action for a player. It considers quest dependencies, hideout upgrade materials, crafting recipes, and recycle returns. Inputs include item data, hideout module definitions, quest requirements, project crafting needs, and the user's current progress. Outputs include the recommended action, specific reasons, and item dependencies.

```typescript
import { DecisionEngine } from './utils/decisionEngine';
import type { Item } from './types/Item';
import type { UserProgress } from './types/UserProgress';

// Initialize decision engine with game data
const engine = new DecisionEngine(
  items,           // All game items
  hideoutModules,  // Hideout upgrade definitions
  quests,          // Quest data with requirements
  projects         // Project crafting requirements
);

// Get decision for a specific item
const userProgress: UserProgress = {
  hideoutLevels: { 'workshop': 2, 'armory': 1 },
  completedQuests: ['quest-001'],
  completedProjects: ['project-alpha'],
  lastUpdated: Date.now()
};

const decision = engine.getDecision(item, userProgress);
// Returns: { 
//   decision: 'keep' | 'sell_or_recycle' | 'situational',
//   reasons: ['Required for quest: Find the Evidence', 'Needed for hideout upgrade: Workshop (Level 3)'],
//   dependencies: ['Find the Evidence', 'Workshop (Level 3)'],
//   recycleValueExceedsItem: false
// }

// Get all items with decisions
const itemsWithDecisions = engine.getItemsWithDecisions(userProgress);
// Returns array of items with decisionData attached

// Get statistics
const stats = engine.getDecisionStats(userProgress);
// Returns: { keep: 45, sell_or_recycle: 120, situational: 38 }

// Find items that use a specific ingredient
const craftingUses = engine.getItemsUsingIngredient('scrap-metal');
// Returns array of Item objects that require scrap-metal in their recipes

```

--------------------------------

### User Progress Persistence with localStorage (TypeScript)

Source: https://context7.com/otdavies/raidercache/llms.txt

Manages user progress, favorites, and filter preferences using localStorage. It provides functions to load, save, and update user progress, including hideout levels, completed quests, and projects. It also handles item favorites and category filters, with an option to reset all progress.

```typescript
import { StorageManager } from './utils/storage';
import type { UserProgress } from './types/UserProgress';

// Load user progress
const progress = StorageManager.loadUserProgress();
// Returns: {
//   hideoutLevels: { 'workshop': 2, 'armory': 1, ... },
//   completedQuests: ['quest-001', 'quest-002'],
//   completedProjects: ['project-alpha'],
//   lastUpdated: 1705032000000
// }

// Save user progress
const updatedProgress: UserProgress = {
  hideoutLevels: { 'workshop': 3 },
  completedQuests: ['quest-001'],
  completedProjects: [],
  lastUpdated: Date.now()
};
StorageManager.saveUserProgress(updatedProgress);

// Update hideout level
StorageManager.updateHideoutLevel('workshop', 3);

// Mark quest/project as completed
StorageManager.completeQuest('quest-003');
StorageManager.completeProject('project-beta');

// Manage favorites
const favorites = StorageManager.loadFavorites();
// Returns: Set<string> of item IDs

const isFavorited = StorageManager.toggleFavorite('legendary-sword');
// Returns: true if now favorited, false if unfavorited

// Category filters (three-state: neutral/include/exclude)
const categoryFilters = StorageManager.loadCategoryFilters();
// Returns: Map<string, 'include' | 'exclude'>

const filters = new Map([
  ['Weapon', 'include'],
  ['Cosmetic', 'exclude']
]);
StorageManager.saveCategoryFilters(filters);

// Reset all progress
StorageManager.resetProgress();
```

--------------------------------

### CDN Assets - UI Map Images

Source: https://context7.com/otdavies/raidercache/llms.txt

Serves map images from the content delivery network.

```APIDOC
## GET /arc-raiders/ui/{mapname}.webp

### Description
Retrieves map images in WebP format from the CDN.

### Method
GET

### Endpoint
`https://cdn.metaforge.app/arc-raiders/ui/{mapname}.webp`

### Path Parameters
- **mapname** (string) - Required - The name of the map.

### Response
#### Success Response (200)
- Returns a WebP image file of the specified map.
```

--------------------------------

### Fuzzy Item Search with Fuse.js (TypeScript)

Source: https://context7.com/otdavies/raidercache/llms.txt

Implements fuzzy search for items, allowing for typos and partial matches. It uses Fuse.js for efficient searching and can be initialized with a list of searchable items. The search index can be updated dynamically, and there's a helper function to determine if an item is cosmetic.

```typescript
import { SearchEngine } from './utils/searchEngine';
import type { SearchableItem } from './utils/searchEngine';

// Initialize with items that include decision data
const searchableItems: SearchableItem[] = itemsWithDecisions;
const searchEngine = new SearchEngine(searchableItems);

// Search for items
const results = searchEngine.search('scrap');
// Returns array of items matching 'scrap' in name, description, type, or id
// Sorted by relevance with threshold of 0.3 for fuzzy matching

// Update search index with new items
searchEngine.updateIndex(updatedItems);

// Search supports typos and partial matches
const typoResults = searchEngine.search('metl');  // Finds 'metal' items
const partialResults = searchEngine.search('leg'); // Finds 'legendary' items

// Check if item is cosmetic
import { isCosmetic } from './utils/searchEngine';
const cosmetic = isCosmetic(item);
// Returns true if name contains: (outfit), (emote), (backpack charm), (color)
```

--------------------------------

### CDN Assets - Map Tiles

Source: https://context7.com/otdavies/raidercache/llms.txt

Serves map tiles for different zoom levels and coordinates from the CDN.

```APIDOC
## GET /arc-raiders/maps/{mapname}/v2/{z}/{x}/{y}.webp

### Description
Retrieves map tiles for specified zoom level (z), x, and y coordinates from the CDN.

### Method
GET

### Endpoint
`https://cdn.metaforge.app/arc-raiders/maps/{mapname}/v2/{z}/{x}/{y}.webp`

### Path Parameters
- **mapname** (string) - Required - The name of the map.
- **z** (integer) - Required - The zoom level.
- **x** (integer) - Required - The x-coordinate.
- **y** (integer) - Required - The y-coordinate.

### Response
#### Success Response (200)
- Returns a WebP image tile for the specified map and coordinates.
```

--------------------------------

### CDN Assets - Item Icons

Source: https://context7.com/otdavies/raidercache/llms.txt

Serves item icons from the content delivery network.

```APIDOC
## GET /icons/{itemid}.webp

### Description
Retrieves item icons in WebP format from the CDN. These are typically converted to PNG locally.

### Method
GET

### Endpoint
`https://cdn.metaforge.app/icons/{itemid}.webp`

### Path Parameters
- **itemid** (string) - Required - The unique identifier of the item.

### Response
#### Success Response (200)
- Returns a WebP image file of the specified item icon.
```

--------------------------------

### MetaForge Supabase - Map Data

Source: https://context7.com/otdavies/raidercache/llms.txt

Retrieves specific map data points from the MetaForge Supabase instance.

```APIDOC
## GET /rest/v1/arc_map_data

### Description
Fetches specific map data points, filterable by map name, from the Supabase database.

### Method
GET

### Endpoint
`https://unhbvkszwhczbjxgetgk.supabase.co/rest/v1/arc_map_data`

### Query Parameters
- **map** (string) - Required - The name of the map to filter by (e.g., `spaceport`).
- **select** (string) - Optional - Specifies which columns to retrieve. Use '*` for all columns.

### Headers
- **apikey** (string) - Required - Your Supabase API key.
- **Authorization** (string) - Required - Bearer token for authentication (uses public anon key).

### Response
#### Success Response (200)
- Returns an array of objects, where each object contains map data for the specified map, including fields like `id`, `subcategory`, `lat`, `lng`, `map`, `category`, and `instance_name`.
```

--------------------------------

### DataLoader - Manage Game Data Loading with TypeScript

Source: https://context7.com/otdavies/raidercache/llms.txt

The dataLoader is a singleton service responsible for fetching and caching game data from JSON files. It automatically resolves file paths and provides functions to load all game data, retrieve item icon URLs, and clear the cache. Price overrides from a separate JSON file are automatically merged into the item values.

```typescript
import { dataLoader } from './utils/dataLoader';

// Load all game data (cached after first call)
const gameData = await dataLoader.loadGameData();
// Returns: {
//   items: Item[],
//   hideoutModules: HideoutModule[],
//   quests: Quest[],
//   projects: Project[],
//   metadata: {
//     lastUpdated: '2026-01-12T03:15:00.000Z',
//     source: 'https://metaforge.app/arc-raiders',
//     version: '2.1.0'
//   }
// }

// Get icon URL for an item
const iconUrl = dataLoader.getIconUrl(item);
// Returns: '/RaiderCache/assets/icons/scrap-metal.png'
// Handles missing icons with transparent placeholder

// Clear cache (useful for testing)
dataLoader.clearCache();

// Price overrides are automatically applied
// Loads from data/priceOverrides.json and merges with item values
// Example override structure:
// {
//   "metadata": {
//     "version": "1.0.0",
//     "lastUpdated": "2026-01-12",
//     "description": "Manual price corrections"
//   },
//   "overrides": {
//     "legendary-sword": {
//       "value": 5000,
//       "source": "Community market data",
//       "confidence": "high"
//     }
//   }
// }

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.