jstudio/README.md

Official Node.js SDK for JStudio's API & WebSocket services - Fast, reliable API for real-time data from Various Games (Roblox)

# JStudio API SDK

Official Node.js SDK for JStudio's API & WebSocket services - Fast, reliable API for real-time data from Various Games (Roblox)

## Installation

```bash
npm install jstudio
```

## Quick Start

```javascript
const jstudio = require('jstudio');

// Connect with your JStudio key
const client = jstudio.connect('Jstudio_key_here');

// Get all stock data
client.stocks.all().then(stock => {
  console.log('Seed stock:', stock.seed_stock);
  console.log('Gear stock:', stock.gear_stock);
});

// Or use the shorthand you requested
const jstudioClient = jstudio.connect('Jstudio_key_here');
jstudioClient.stocks; // Access stock data
```

## Usage Examples

### Getting Stock Data

```javascript
// Get all stock data
const allStock = await client.stocks.all();

// Get specific stock types
const seeds = await client.stocks.seeds();
const gear = await client.stocks.gear();
const eggs = await client.stocks.eggs();
const cosmetics = await client.stocks.cosmetics();
const eventShop = await client.stocks.eventShop();
const travelingMerchant = await client.stocks.travelingMerchant();
```

### Weather Information

```javascript
// Get all weather data
const weather = await client.weather.all();

// Get only active weather events
const activeWeather = await client.weather.active();
```

### Item Information

```javascript
// Get all items
const allItems = await client.items.all();

// Get items by type
const seeds = await client.items.seeds();
const gear = await client.items.gear();
const eggs = await client.items.eggs();

// Get specific item
const item = await client.items.get('apple');
```

### Fruit Calculator

```javascript
// Calculate fruit value
const result = await client.calculator.calculate({
  Name: 'Apple',
  Weight: '5.2',
  Variant: 'Golden',
  Mutation: 'Shiny'
});

// Get all calculation data
const allCalculationData = await client.calculator.getAllData();
```

### Images

```javascript
// Get image URL for an item
const imageUrl = client.images.getUrl('apple');
console.log(imageUrl); // https://api.joshlei.com/v2/growagarden/image/apple
```

### Utility Functions

```javascript
// Health check
const health = await client.healthCheck();

// Cache status
const cacheStatus = await client.getCacheStatus();

// Current event
const currentEvent = await client.getCurrentEvent();
```

## API Reference

### JStudioClient

#### Constructor Options

```typescript
interface JStudioConfig {
  apiKey: string;          // Required: Your JStudio key
  baseURL?: string;        // Optional: API base URL (default: 'https://api.joshlei.com')
  timeout?: number;        // Optional: Request timeout in ms (default: 30000)
  retries?: number;        // Optional: Number of retries for failed requests (default: 3)
  retryDelay?: number;     // Optional: Delay between retries in ms (default: 1000)
}
```

#### Stocks

- `client.stocks.all()` - Get all stock data
- `client.stocks.seeds()` - Get seed stock
- `client.stocks.gear()` - Get gear stock
- `client.stocks.eggs()` - Get egg stock
- `client.stocks.cosmetics()` - Get cosmetic stock
- `client.stocks.eventShop()` - Get event shop stock
- `client.stocks.travelingMerchant()` - Get traveling merchant stock

#### Weather

- `client.weather.all()` - Get all weather data
- `client.weather.active()` - Get only active weather events

#### Items

- `client.items.all(type?)` - Get all items, optionally filtered by type
- `client.items.get(itemId)` - Get specific item by ID
- `client.items.seeds()` - Get seed items
- `client.items.gear()` - Get gear items
- `client.items.eggs()` - Get egg items
- `client.items.cosmetics()` - Get cosmetic items
- `client.items.events()` - Get event items
- `client.items.pets()` - Get pet items
- `client.items.seedpacks()` - Get seed pack items
- `client.items.weather()` - Get weather items

#### Calculator

- `client.calculator.calculate(params)` - Calculate fruit value
- `client.calculator.getAllData()` - Get all calculation data

#### Images

- `client.images.getUrl(itemId)` - Get image URL for item

#### Utilities

- `client.healthCheck()` - API health check
- `client.getCacheStatus()` - Get cache performance metrics
- `client.getCurrentEvent()` - Get current event information

## Error Handling

The SDK includes comprehensive error handling:

```javascript
try {
  const stock = await client.stocks.all();
} catch (error) {
  if (error instanceof jstudio.JStudioApiError) {
    console.log('API Error:', error.message);
    console.log('Status:', error.status);
    console.log('Data:', error.data);
    
    if (error.status === 429) {
      console.log('Rate limited. Retry after:', error.retryAfter);
    }
  } else {
    console.log('Other error:', error.message);
  }
}
```

## Rate Limiting

The API uses rate limiting based on your JStudio key's configuration. When you hit rate limits:

- The SDK will automatically retry for server errors (5xx)
- Rate limit errors (429) will include retry timing information
- Check your JStudio key limits and usage in the JStudio dashboard

## Getting an JStudio key

1. Visit [JStudio API Community](https://discord.gg/kCryJ8zPwy)
3. Generate a new JStudio key
4. Use the key in your application

## Support

- **Documentation**: [https://api.joshlei.com/docs](https://api.joshlei.com/docs)
- **Discord**: [https://discord.gg/kCryJ8zPwy](https://discord.gg/kCryJ8zPwy)

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

---

Made with ❤️ by JStudio for the community.