npm package: @resypress/theme-sdk
Description: SDK for building ResyPress themes - reusable components, API services, and utilities
Author: ResyPress
Latest version: 0.1.7

# @resypress/theme-sdk

SDK for building ResyPress themes - reusable components, API services, and utilities.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Open Source

This project is open source and available under the [MIT License](LICENSE).

## Installation

```bash
npm install @resypress/theme-sdk
```

## Quick Start

### Initialize the SDK

The SDK automatically detects configuration from multiple sources. You can initialize it with minimal or no configuration:

```typescript
import { init } from '@resypress/theme-sdk';

// Option 1: Auto-detect from domain (recommended for production)
// The SDK will automatically detect account from the current domain
await init();

// Option 2: Override specific values
await init({
  accountID: '123',
  apiBaseUrl: 'https://api.resypress.com/api',
  locale: 'en',
});

// Option 3: Use environment variables in development
// In your theme project, create a .env file with:
// VITE_RESYPRESS_ACCOUNT_ID=123
// VITE_RESYPRESS_API_BASE_URL=http://localhost:8080/api
// VITE_RESYPRESS_LOCALE=en
// Then pass them to init():
await init({
  accountID: import.meta.env.VITE_RESYPRESS_ACCOUNT_ID,
  apiBaseUrl: import.meta.env.VITE_RESYPRESS_API_BASE_URL || '/api',
  locale: import.meta.env.VITE_RESYPRESS_LOCALE || 'en',
});
```

### Configuration Priority

The SDK uses the following priority order (highest to lowest):

1. **Explicit init() options** - Values passed directly to `init()`
2. **localStorage overrides** - For runtime testing (useful for development)
   - `RESYPRESS_ACCOUNT_ID`
   - `RESYPRESS_API_BASE_URL`
   - `RESYPRESS_LOCALE`
3. **window.__RESYPRESS__CONFIG__** - Injected config object (from config.json or server-side)
4. **Domain auto-detection** - Automatically detects account from current hostname
   - Uses the FULL domain name (e.g., `example.com` or `www.example.com`)
   - Matches backend's WebsiteDomain lookup behavior (looks up by full domain_value)
   - Skips localhost and IP addresses
5. **Default values** - Fallback defaults (`/api` for base URL, `en` for locale)

### Environment Variables in Development

For development, you can use environment variables in your theme project's `.env` file:

```env
VITE_RESYPRESS_ACCOUNT_ID=123
VITE_RESYPRESS_API_BASE_URL=http://localhost:8080/api
VITE_RESYPRESS_LOCALE=en
```

Then pass them to `init()`:

```typescript
await init({
  accountID: import.meta.env.VITE_RESYPRESS_ACCOUNT_ID,
  apiBaseUrl: import.meta.env.VITE_RESYPRESS_API_BASE_URL || '/api',
  locale: import.meta.env.VITE_RESYPRESS_LOCALE || 'en',
});
```

**Note:** The SDK cannot directly access your project's `import.meta.env` at runtime, so you need to pass environment variables explicitly to `init()`.

### Use API Services

```typescript
import { apiClient } from '@resypress/theme-sdk';

// Make API calls
const properties = await apiClient('/public/{accountID}/properties');
```

### Use Utilities

```typescript
import { getText } from '@resypress/theme-sdk';

// Handle multilingual strings
const name = getText(property.name, 'en'); // Returns 'en' version or fallback
```

## Features

- ✅ **Core Configuration** - Initialize and manage SDK configuration
- ✅ **API Client** - Type-safe API client with error handling
- ✅ **i18n Utilities** - Multilingual string handling
- ✅ **React Components** - Pre-built UI components (PropertyCard, BookingForm, GuestPortalLogin, GuestPortalChat, etc.)
- ✅ **React Hooks** - Data fetching hooks with React Query integration
- ✅ **API Services** - Direct API access functions

## Documentation

- **[Usage Guide](../../docs/THEME_SDK_USAGE_GUIDE.md)** - Complete guide for using the SDK (components, hooks, services, utilities)
- **[Implementation Plan](../../THEME_SDK.md)** - Detailed technical implementation documentation

## Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Type check
npm run type-check

# Watch mode
npm run dev
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.