npm package: @stringboot/web-sdk
Description: StringBoot Web SDK for browser-based internationalization with delta sync
Author: StringBoot Engineering Team
Latest version: 2.0.1

# StringBoot Web SDK

[![npm version](https://badge.fury.io/js/%40stringboot%2Fweb-sdk.svg)](https://www.npmjs.com/package/@stringboot/web-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Modern internationalization (i18n) SDK for web applications** with offline-first caching, automatic updates, and React hooks.

## Why StringBoot?

- 🚀 **Quick Setup** - Initialize with one API call
- 🔄 **Delta Sync** - Efficient updates using ETag-based synchronization
- 💾 **Offline-First** - Multi-layer caching (Memory → IndexedDB → Network)
- ⚛️ **React Hooks** - Built-in React integration
- 🎯 **TypeScript** - Full type safety included
- 📦 **Lightweight** - Optimized bundle size
- ❓ **FAQ Support** - Built-in FAQ provider with tag-based filtering
- 🧪 **A/B Testing** - Native experiment tracking and analytics integration

## Installation

```bash
npm install @stringboot/web-sdk
```

## Quick Start

### JavaScript / TypeScript

```javascript
import StringBoot from '@stringboot/web-sdk';

// 1. Initialize once at app startup
await StringBoot.initialize({
  apiToken: 'YOUR_API_TOKEN',
  baseUrl: 'https://api.stringboot.com',
  defaultLanguage: 'en'
});

// 2. Get strings anywhere in your app
const welcomeText = await StringBoot.get('welcome_message');
console.log(welcomeText); // "Welcome to our app!"

// 3. Change language instantly
await StringBoot.changeLanguage('es');
```

### React

```tsx
import { useStringBoot, useString, useLanguage } from '@stringboot/web-sdk/react';

function App() {
  const { initialized, error } = useStringBoot({
    apiToken: 'YOUR_API_TOKEN',
    baseUrl: 'https://api.stringboot.com',
    defaultLanguage: 'en'
  });

  if (!initialized) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return <MyApp />;
}

function MyComponent() {
  const title = useString('page_title');
  const [lang, setLang] = useLanguage();

  return (
    <div>
      <h1>{title}</h1>
      <select value={lang} onChange={(e) => setLang(e.target.value)}>
        <option value="en">English</option>
        <option value="es">Español</option>
      </select>
    </div>
  );
}
```

## FAQ Provider

```javascript
// Initialize FAQ Provider separately
await StringBoot.FAQ.initialize({
  apiToken: 'YOUR_API_TOKEN',
  baseUrl: 'https://api.stringboot.com',
  cacheSize: 200
});

// Fetch all FAQs
const allFAQs = await StringBoot.FAQ.getFAQs({
  tag: 'all',
  lang: 'en',
  allowNetworkFetch: true
});

// Fetch FAQs by tag with sub-tag filtering
const paymentFAQs = await StringBoot.FAQ.getFAQs({
  tag: 'payments',
  subTags: ['refunds', 'disputes'],
  lang: 'en',
  allowNetworkFetch: true
});
```

## Core Features

### String Management
- `initialize(config)` - Initialize SDK
- `get(key, lang?)` - Get a single string
- `watch(key, callback, lang?)` - Subscribe to string updates
- `changeLanguage(lang)` - Switch languages
- `getActiveLanguages()` - Get available languages
- `getCurrentLanguage()` - Get current language
- `syncNow(lang?)` - Manual sync
- `forceRefresh(lang?)` - Clear cache and refresh
- `getCacheStats(lang?)` - Get cache statistics
- `clearAllCaches()` - Clear all caches

### React Hooks
- `useStringBoot(config)` - Initialize SDK
- `useString(key, lang?)` - Get string with auto-updates
- `useStrings(keys, lang?)` - Get multiple strings
- `useLanguage()` - Manage language switching
- `useActiveLanguages()` - Get available languages
- `useSync()` - Manual sync control

### FAQ Provider
- `FAQ.initialize(config)` - Initialize FAQ Provider
- `FAQ.getFAQs(options)` - Get FAQs with filtering
- `FAQ.refreshFromNetwork(lang?, tag?)` - Force refresh
- `FAQ.getAvailableTags(lang?)` - Get all tags
- `FAQ.clearCache(lang?)` - Clear FAQ cache
- `FAQ.clearMemoryCache()` - Clear memory cache

## Complete Documentation

**📖 For comprehensive guides and examples, visit:**

### [https://docs.stringboot.com/web-sdk](https://docs.stringboot.com/web-sdk)

## Key Features

### Offline-First Architecture
Multi-layer caching system:
1. **Memory Cache (LRU)** - Fast in-memory lookups
2. **IndexedDB** - Persistent offline storage
3. **Network (Delta Sync)** - ETag-based efficient updates

### Language Management
- Automatic browser language detection
- Language persistence across sessions
- Reactive language switching
- Multi-tab synchronization via BroadcastChannel

### FAQ System
- **2-level filtering**: Mandatory tags + optional sub-tags
- **"All" tag support**: Fetch entire FAQ catalog
- **Multi-language**: Automatic fallback to English
- **Delta sync**: Only downloads changed FAQs
- **Offline support**: Full functionality without network

### A/B Testing
- Automatic experiment assignment
- Analytics handler integration (Google Analytics, Mixpanel, etc.)
- Cached assignments for consistency
- No code changes required

## TypeScript Support

Full TypeScript support with comprehensive types:

```typescript
import StringBoot from '@stringboot/web-sdk';
import type {
  StringBootConfig,
  ActiveLanguage,
  FAQ,
  GetFAQsOptions,
  ExperimentAssignment
} from '@stringboot/web-sdk';
```

## Browser Support

- Chrome 87+
- Firefox 78+
- Safari 14+
- Edge 88+

**Required APIs:** IndexedDB, localStorage, Fetch API, ES2020

## Demo Application

Check out the **[StringBoot Demo Web App](https://github.com/Stringboot-SDK/Stringboot-Demo-Web-App)** for complete working examples:
- String management with language switching
- FAQ browsing with tag filtering
- React hooks integration
- Offline functionality

## Getting Help

- 📖 **Documentation**: [https://docs.stringboot.com/web-sdk](https://docs.stringboot.com/web-sdk)
- 🐛 **Report Issues**: [GitHub Issues](https://github.com/Stringboot-SDK/Stringboot-Demo-Web-App/issues)
- 📧 **Email Support**: developer@stringboot.com

## License

MIT © StringBoot Engineering Team

---

**Made with ❤️ by the StringBoot Team**