@masterunoco/casinowebengine-api 0.1.0

package/README.md

@@ -0,0 +1,227 @@
+# 🕹️ Gaming Platform – GameService SDK
+
+A **TypeScript front-end SDK** for interacting with the `gameService` and related APIs across casino front-end projects.  
+It provides a unified interface for games, authentication, content, player preferences, website settings, and more — all with full type safety and automatic JWT handling.
+
+---
+
+## ✨ Features
+
+- 🤩 **Typed API layer** – all endpoints return strongly-typed responses.
+- 🔐 **Built-in JWT auth** – automatically attaches `Authorization: JWT <token>` to protected requests.
+- 🌐 **Public + private endpoints** – transparent auth handling (`none`, `optional`, `required`).
+- ⚙️ **Configurable** – base URL, brand, currency, language, and timeout.
+- 🗾 **Persistent storage** – stores tokens and user data via localStorage helper.
+- 🧠 **Framework-agnostic** – works with any front-end (React, Vue, Next.js, etc.).
+- 🥷 **Ready for npm** – ships with ESM + CJS + `.d.ts` types.
+
+---
+
+## 📦 Installation
+
+### From npm (when published)
+```bash
+npm install @cwe/frontend-sdk
+```
+
+### Local development
+If the SDK is cloned locally:
+```bash
+# In SDK directory
+npm run build
+
+# In your front-end project
+npm install ../path-to/gameservice-sdk
+# or
+npm i file:../gameservice-sdk
+```
+
+### Workspace monorepo
+If both live in the same repo:
+```json
+"dependencies": {
+  "@cwe/frontend-sdk": "workspace:*"
+}
+```
+
+---
+
+## 🧰 Basic Setup
+
+```ts
+import { createGameSDK } from '@cwe/frontend-sdk';
+
+const sdk = createGameSDK({
+  baseUrl: import.meta.env.VITE_GAMESERVICE_URL,
+  brand: 'BrandA',
+  defaultLanguage: 'en',
+  defaultCurrency: 'USD',
+  storage: localStorage,
+  storageKey: 'gp.jwt',
+});
+```
+
+---
+
+## 🔑 Authentication
+
+```ts
+// Login (stores JWT in localStorage automatically)
+await sdk.auth.login('player3', '123123', '<recaptcha-token>');
+
+// Check if authenticated
+if (sdk.auth.isAuthenticated()) {
+  console.log('Logged in as', sdk.auth.getUser()?.username);
+}
+
+// Logout (clears token + user)
+sdk.auth.clear();
+```
+
+---
+
+## 🤩 Example Usage
+
+### 🎮 Games
+```ts
+// Search games
+const result = await sdk.games.searchGames({ category: 'slots', page: 1 });
+console.log(result.totalCount, result.results[0].name);
+
+// Get demo link
+const demo = await sdk.games.getDemoLink(1234);
+window.open(demo.gameLink, '_blank');
+```
+
+### 📄 Content Pages
+```ts
+const pages = await sdk.settings.listContentPages();
+const about = await sdk.settings.getContentItem('about-us', 'en');
+console.log(about.title);
+```
+
+### ⚙️ Preferences
+```ts
+const prefs = await sdk.settings.getPreferences();
+await sdk.settings.updatePreferences({ displayMode: 'dark' });
+```
+
+### 💬 Website Settings
+```ts
+const footer = await sdk.settings.getWebSetting('en');
+const providers = await sdk.settings.getWebSettingProviders('en');
+const support = await sdk.settings.getSupportEmail('en');
+```
+
+### 🌍 Geolocation
+```ts
+const geo = await sdk.geolocation.getGeolocation();
+console.log(geo);
+```
+
+---
+
+## 🧱 Architecture
+
+```
+src/
+├─ sdk.ts                # Core GameSDK class
+├─ index.ts              # Barrel exports
+├─ http/client.ts        # Fetch wrapper with timeout & authPolicy
+├─ auth/jwtAuth.ts       # JWT lifecycle (login, store, clear)
+├─ apis/
+│  ├─ games.ts           # /games, /games/search
+│  ├─ settings.ts        # /content-pages, /website-settings, /player/preferences
+│  ├─ geo.ts             # /geo/location
+│  └─ ... (other feature modules)
+├─ types/
+│  ├─ auth.ts
+│  ├─ gamesSearch.ts
+│  ├─ settings.ts
+│  └─ signup.ts
+└─ localStorage.ts       # Persistent storage helper
+```
+
+Each API module uses the shared `HttpClient` and defines its own types and interfaces.
+
+---
+
+## 🗾 Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `baseUrl` | `string` | Base API URL for gameService |
+| `brand` | `string` | Optional brand name for `X-Brand` header |
+| `defaultLanguage` | `string` | Default language header |
+| `defaultCurrency` | `string` | Default currency header |
+| `storage` | `Storage` | Browser storage (e.g., `localStorage`) |
+| `storageKey` | `string` | Key under which JWT is stored |
+| `timeoutMs` | `number` | Request timeout in milliseconds |
+
+---
+
+## 🥪 Development
+
+```bash
+# Build for production
+npm run build
+
+# Watch mode
+npm run dev
+
+# Type-check only
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+---
+
+## 🥱 Local Testing with Front-end
+
+In your front-end project:
+
+```ts
+import { createGameSDK } from '@cwe/frontend-sdk';
+
+const sdk = createGameSDK({
+  baseUrl: 'https://api.yourdomain.com/game-service',
+  storage: localStorage,
+  storageKey: 'gp.jwt',
+});
+
+const games = await sdk.games.searchGames({ category: 'slots' });
+console.log(games.results.length);
+```
+
+---
+
+## 🤩 Building Blocks (Available APIs)
+
+| Module | Description |
+|---------|-------------|
+| `auth` | Handles login, token management, user retrieval |
+| `games` | Search, list, and launch games |
+| `settings` | Content pages, banners, preferences, currencies, and website settings |
+| `geolocation` | Detect and cache player location |
+| `localStorage` | Utility for token, user, and geo persistence |
+
+---
+
+## 🗾 Build Output
+
+```
+dist/
+├─ index.js         (ESM)
+├─ index.cjs        (CJS)
+└─ index.d.ts       (Type declarations)
+```
+
+---
+
+## 🗾 License
+
+MIT © 2025 Gaming Platform  
+Developed by **Eyal (Venus Technology / Gaming Platform)**
+