flipflag-sdk 1.1.0

package/README.md

@@ -0,0 +1,713 @@
+# FlipFlag SDK
+
+A comprehensive, framework-agnostic SDK for feature flags and A/B testing with support for React, Vue, Next.js, React Native, and vanilla JavaScript.
+
+## 🚀 Features
+
+- **Multi-framework support**: React, Vue, Next.js, React Native, and vanilla JavaScript
+- **A/B Testing**: Built-in support for experiment tracking and event recording
+- **Caching**: Intelligent caching with configurable TTL
+- **TypeScript**: Full TypeScript support with comprehensive type definitions
+- **SSR Support**: Optimized for server-side rendering with Next.js
+- **Retry Logic**: Automatic retry with exponential backoff
+- **Rate Limiting**: Built-in handling of API rate limits
+- **Offline Support**: Graceful fallbacks and offline capabilities
+
+## 📦 Installation
+
+```bash
+npm install flipflag-sdk
+# or
+yarn add flipflag-sdk
+# or
+pnpm add flipflag-sdk
+```
+
+## 🔧 Configuration
+
+First, create a configuration object:
+
+```typescript
+import { FlipFlagConfig } from "flipflag-sdk";
+
+const config: FlipFlagConfig = {
+  apiKey: "ff_your_project_api_key",
+  projectId: "your-project-uuid",
+  environment: "production", // optional: 'dev', 'staging', 'prod'
+  userId: "user123", // optional: user identification for A/B testing
+  baseUrl: "https://app.flipflag.ru", // optional, defaults to production
+  pullInterval: 60000, // optional: auto-refresh interval in ms (60 seconds)
+  cacheTimeout: 30000, // optional, cache TTL in ms
+  retryAttempts: 3, // optional, number of retry attempts
+  retryDelay: 1000, // optional, base delay between retries in ms
+};
+```
+
+## 🔄 Pull Interval Architecture
+
+SDK работает на основе **pull интервала** - это значит, что:
+
+1. **Автоматическое обновление**: SDK автоматически получает свежие данные каждые `pullInterval` миллисекунд
+2. **Мгновенный доступ**: Хуки возвращают значения из локального состояния, без задержек
+3. **Фоновая синхронизация**: Обновление происходит в фоне, не блокируя UI
+4. **Идентификация пользователя**: A/B тесты и персонализированные флаги привязываются к `userId`
+
+### Идентификация пользователя
+
+```typescript
+import { identifyUser } from "flipflag-sdk/react";
+
+// После авторизации пользователя
+identifyUser({
+  userId: "user123",
+  userProperties: {
+    name: "John Doe",
+    email: "john@example.com",
+    plan: "premium",
+  },
+});
+```
+
+## 🎯 React Usage
+
+### Basic Setup
+
+```tsx
+import React from "react";
+import { FeatureFlagProvider, useFeatureFlag } from "flipflag-sdk/react";
+
+function App() {
+  return (
+    <FeatureFlagProvider config={config}>
+      <MyComponent />
+    </FeatureFlagProvider>
+  );
+}
+
+function MyComponent() {
+  const {
+    value: darkModeEnabled,
+    loading,
+    error,
+  } = useFeatureFlag("dark_mode");
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return (
+    <div className={darkModeEnabled ? "dark-theme" : "light-theme"}>
+      <h1>Welcome to FlipFlag!</h1>
+    </div>
+  );
+}
+```
+
+### Multiple Flags
+
+```tsx
+import { useFeatureFlags } from "flipflag-sdk/react";
+
+function MyComponent() {
+  const { flags, loading } = useFeatureFlags([
+    "dark_mode",
+    "new_checkout",
+    "advanced_search",
+  ]);
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {flags.new_checkout && <NewCheckoutFlow />}
+      {flags.advanced_search && <AdvancedSearch />}
+    </div>
+  );
+}
+```
+
+### A/B Testing
+
+```tsx
+import { useABTest } from "flipflag-sdk/react";
+
+function ButtonComponent() {
+  const {
+    variant: buttonColor,
+    loading,
+    recordEvent,
+  } = useABTest("button_color_test", {
+    userId: "user123",
+  });
+
+  const handleClick = () => {
+    recordEvent("click", { page: "/home" });
+  };
+
+  if (loading) return <button>Loading...</button>;
+
+  return (
+    <button style={{ backgroundColor: buttonColor }} onClick={handleClick}>
+      Click me!
+    </button>
+  );
+}
+```
+
+## ⚡ Next.js Usage
+
+### App Router (with SSR)
+
+```tsx
+// app/layout.tsx
+import { FlipflagProvider } from "flipflag/next";
+
+export default function RootLayout({
+  children,
+  serverFlags,
+}: {
+  children: React.ReactNode;
+  serverFlags?: any;
+}) {
+  return (
+    <html>
+      <body>
+        <FlipflagProvider config={config} serverFlags={serverFlags}>
+          {children}
+        </FlipflagProvider>
+      </body>
+    </html>
+  );
+}
+
+// app/page.tsx
+import { getServerSideFlags } from "flipflag/next";
+
+export default async function Page() {
+  const serverFlags = await getServerSideFlags(config, [
+    "dark_mode",
+    "new_feature",
+  ]);
+
+  return <RootLayout serverFlags={serverFlags}>...</RootLayout>;
+}
+```
+
+### Pages Router
+
+```tsx
+// pages/_app.tsx
+import { FlipflagProvider } from "flipflag/next";
+
+function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <FlipflagProvider config={config} serverFlags={pageProps.serverFlags}>
+      <Component {...pageProps} />
+    </FlipflagProvider>
+  );
+}
+
+// pages/index.tsx
+import { getServerSideFlags } from "flipflag/next";
+
+export async function getServerSideProps() {
+  const serverFlags = await getServerSideFlags(config, ["dark_mode"]);
+
+  return {
+    props: {
+      serverFlags,
+    },
+  };
+}
+```
+
+## 🟢 Vue Usage
+
+### Basic Setup
+
+```typescript
+// main.ts
+import { createApp } from "vue";
+import { createFlipFlagPlugin } from "flipflag/vue";
+import App from "./App.vue";
+
+const config = {
+  apiKey: "ff_your_project_api_key",
+  projectId: "your-project-uuid",
+  environment: "production",
+  userId: "user123",
+  baseUrl: "https://app.flipflag.ru",
+  pullInterval: 60000, // Auto-refresh every 60 seconds
+  cacheTimeout: 30000,
+  retryAttempts: 3,
+  retryDelay: 1000,
+};
+
+const app = createApp(App);
+app.use(createFlipFlagPlugin(), config);
+app.mount("#app");
+```
+
+### Using Hooks
+
+```vue
+<template>
+  <div>
+    <h1 v-if="darkMode">🌙 Dark Mode</h1>
+    <h1 v-else>☀️ Light Mode</h1>
+
+    <div v-for="feature in features" :key="feature.key">
+      <h3>{{ feature.name }}</h3>
+      <span :class="{ enabled: feature.enabled, disabled: !feature.enabled }">
+        {{ feature.enabled ? "✅ Enabled" : "❌ Disabled" }}
+      </span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {
+  useFeatureFlag,
+  useFeatureFlags,
+  useABTest,
+  identifyUser,
+} from "flipflag/vue";
+
+const { value: darkMode } = useFeatureFlag("dark_mode");
+
+const { flags } = useFeatureFlags([
+  "new_ui",
+  "advanced_search",
+  "social_features",
+]);
+
+const { variant, variantId } = useABTest("cta_button_test", {
+  userId: "vue-user-123",
+});
+
+// Identify user
+identifyUser({
+  userId: "vue-user-123",
+  userProperties: {
+    name: "Vue User",
+    version: "3.0",
+  },
+});
+</script>
+```
+
+## 📱 React Native Usage
+
+### Basic Setup
+
+```tsx
+// App.tsx
+import React from "react";
+import { FeatureFlagProvider } from "flipflag/react-native";
+import { useFeatureFlag, useABTest, identifyUser } from "flipflag/react-native";
+
+const config = {
+  apiKey: "ff_your_project_api_key",
+  projectId: "your-project-uuid",
+  environment: "production",
+  userId: "rn-user-123",
+  baseUrl: "https://app.flipflag.ru",
+  pullInterval: 60000,
+  cacheTimeout: 30000,
+  retryAttempts: 3,
+  retryDelay: 1000,
+};
+
+function App() {
+  return (
+    <FeatureFlagProvider config={config}>
+      <MyComponent />
+    </FeatureFlagProvider>
+  );
+}
+```
+
+### Using Hooks
+
+```tsx
+import React from "react";
+import { View, Text, TouchableOpacity } from "react-native";
+import {
+  useFeatureFlag,
+  useFeatureFlags,
+  useABTest,
+  identifyUser,
+} from "flipflag/react-native";
+
+function MyComponent() {
+  const { value: darkMode, loading } = useFeatureFlag("dark_mode");
+
+  const { flags } = useFeatureFlags([
+    "new_ui",
+    "offline_mode",
+    "push_notifications",
+  ]);
+
+  const { variant, variantId, recordEvent } = useABTest("cta_button_test", {
+    userId: "rn-user-123",
+  });
+
+  const handleIdentifyUser = () => {
+    identifyUser({
+      userId: "rn-user-123",
+      userProperties: {
+        platform: "iOS",
+        version: "1.0.0",
+        device: "iPhone",
+      },
+    });
+  };
+
+  const handleButtonPress = () => {
+    recordEvent("click", {
+      screen: "home",
+      element: "cta_button",
+    });
+  };
+
+  if (loading) {
+    return <Text>Loading...</Text>;
+  }
+
+  return (
+    <View style={{ backgroundColor: darkMode ? "#333" : "#fff" }}>
+      <Text style={{ color: darkMode ? "#fff" : "#333" }}>
+        {darkMode ? "🌙 Dark Mode" : "☀️ Light Mode"}
+      </Text>
+
+      <TouchableOpacity onPress={handleIdentifyUser}>
+        <Text>👤 Identify User</Text>
+      </TouchableOpacity>
+
+      <TouchableOpacity
+        onPress={handleButtonPress}
+        style={{ backgroundColor: variant || "#007bff" }}
+      >
+        <Text>Test Button (Variant: {variantId})</Text>
+      </TouchableOpacity>
+    </View>
+  );
+}
+```
+
+## 🌐 Vanilla JavaScript Usage
+
+```javascript
+import { createFeatureFlagManager } from "flipflag/js";
+
+const flagManager = createFeatureFlagManager({
+  config,
+  autoRefresh: true,
+  refreshInterval: 30000, // 30 seconds
+});
+
+// Get a single flag
+const darkModeEnabled = await flagManager.getFlag("dark_mode");
+
+// Get multiple flags
+const flags = await flagManager.getFlags(["dark_mode", "new_checkout"]);
+
+// Subscribe to flag changes
+const unsubscribe = flagManager.onFlagChange("dark_mode", (value) => {
+  console.log("Dark mode changed to:", value);
+  updateTheme(value);
+});
+
+// A/B Testing
+const { variant, variantId } = await flagManager.getABTestVariant(
+  "button_test",
+  "user123"
+);
+await flagManager.recordABTestEvent("button_test", "user123", "click", {
+  page: "/home",
+  element: "hero_button",
+});
+
+// Cleanup
+unsubscribe();
+flagManager.stopAutoRefresh();
+```
+
+## 🎨 Advanced Usage
+
+### Custom Cache Strategy
+
+```typescript
+import { FlipFlagSDK } from "flipflag";
+
+const sdk = new FlipFlagSDK({
+  ...config,
+  cacheTimeout: 60000, // 1 minute cache
+});
+
+// Manual cache management
+sdk.clearCache(); // Clear all cache
+sdk.clearCache("flags:project123:prod"); // Clear specific cache entry
+```
+
+### Error Handling and Fallbacks
+
+```tsx
+const { value: featureEnabled, error } = useFeatureFlag(
+  "experimental_feature",
+  {
+    fallbackValue: false, // Use false if API fails
+  }
+);
+
+if (error) {
+  console.warn("Feature flag error:", error);
+  // Continue with fallback behavior
+}
+```
+
+### Retry Configuration
+
+```typescript
+const sdk = new FlipFlagSDK({
+  ...config,
+  retryAttempts: 5,
+  retryDelay: 2000, // 2 second base delay
+});
+```
+
+## 🔄 A/B Testing Events
+
+The SDK supports tracking various events for your A/B tests:
+
+```typescript
+// Track different types of events
+recordEvent("view"); // User viewed the variant
+recordEvent("click", { element: "button" }); // User clicked something
+recordEvent("conversion", { revenue: 29.99 }); // User completed a conversion
+recordEvent("custom_event", { customData: "value" }); // Custom event
+```
+
+## 📱 Framework-Specific Features
+
+### React
+
+- ✅ Hooks: `useFeatureFlag`, `useFeatureFlags`, `useABTest`
+- ✅ Context provider for state management
+- ✅ Automatic re-renders on flag changes
+- ✅ TypeScript support
+
+### Next.js
+
+- ✅ SSR/SSG support with `getServerSideFlags`
+- ✅ Hydration-safe flag values
+- ✅ Static generation with `getStaticPropsWithFlags`
+- ✅ App Router and Pages Router support
+
+### Vue
+
+- ✅ Composition API hooks (`useFeatureFlag`, `useFeatureFlags`, `useABTest`)
+- ✅ Vue plugin for global state management
+- ✅ Reactive flag values with automatic updates
+- ✅ Full TypeScript support
+- ✅ Plugin-based dependency injection
+
+### React Native
+
+- ✅ React hooks (`useFeatureFlag`, `useFeatureFlags`, `useABTest`)
+- ✅ Offline storage with AsyncStorage
+- ✅ Provider pattern for state management
+- ✅ Network-aware caching
+- ✅ Native performance optimizations
+
+### Vanilla JavaScript
+
+- ✅ Feature flag manager with event subscriptions
+- ✅ Auto-refresh capabilities
+- ✅ Memory-efficient caching
+- ✅ Framework-agnostic API
+
+## 🔒 Security Best Practices
+
+1. **API Key Storage**: Never expose API keys in client-side code
+2. **Environment Variables**: Use environment variables for configuration
+3. **Rate Limiting**: SDK handles rate limiting automatically
+4. **Error Handling**: Always provide fallback values for critical features
+
+```typescript
+// Secure configuration example
+const config = {
+  apiKey: process.env.FLIPFLAG_API_KEY!,
+  projectId: process.env.FLIPFLAG_PROJECT_ID!,
+  environment: process.env.NODE_ENV === "production" ? "prod" : "dev",
+};
+```
+
+## 🚀 Production Optimization
+
+### Caching Strategy
+
+```typescript
+const config = {
+  ...baseConfig,
+  cacheTimeout: 300000, // 5 minutes for production
+};
+```
+
+### Bundle Splitting
+
+```typescript
+// Only import what you need
+import { useFeatureFlag } from "flipflag/react"; // Tree-shakable
+```
+
+### CDN Deployment
+
+Host the SDK on a CDN for faster loading:
+
+```html
+<script src="https://cdn.example.com/flipflag.js"></script>
+```
+
+## 📊 Monitoring and Analytics
+
+The SDK provides built-in metrics collection:
+
+- Request success/failure rates
+- Cache hit rates
+- A/B test conversion tracking
+- Performance metrics
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Development mode with watch
+npm run dev
+```
+
+## 🎮 Demo Projects
+
+Протестируйте SDK в действии! В папке `demo/` находятся полнофункциональные примеры:
+
+### Быстрый запуск всех демо
+
+```bash
+cd demo
+./start-all.sh start
+```
+
+### Индивидуальный запуск
+
+```bash
+# React demo
+cd demo/react-demo && npm install && npm link flipflag && npm start
+
+# Next.js demo
+cd demo/next-demo && npm install && npm link flipflag && npm run dev
+
+# Vue demo
+cd demo/vue-demo && npm install && npm link flipflag && npm run dev
+```
+
+### Что демонстрируют демо-проекты
+
+- ✅ **Feature Flags** - Управление видимостью функций
+- ✅ **A/B Testing** - Тестирование различных вариантов
+- ✅ **Caching** - Интеллектуальное кэширование
+- ✅ **Error Handling** - Обработка ошибок и fallback значения
+- ✅ **Real-time Updates** - Обновление флагов без перезагрузки
+
+## 📦 Publishing Guide
+
+Готовы опубликовать пакет на npm? Следуйте подробному руководству:
+
+👉 **[PUBLISH_GUIDE.md](./PUBLISH_GUIDE.md)** - Полное руководство по публикации
+
+### Краткая версия
+
+```bash
+# Подготовка
+npm run build
+npm login
+
+# Публикация
+npm publish
+
+# Проверка
+npm view flipflag
+```
+
+## 📚 API Reference
+
+### Core SDK Methods
+
+#### `getFlags(projectId?, environment?)`
+
+Get all feature flags for a project.
+
+#### `getFlag(flagName, projectId?, environment?)`
+
+Get a specific feature flag value.
+
+#### `getAbTestVariant(testName, userId, projectId?)`
+
+Get A/B test variant for a user.
+
+#### `recordAbTestEvent(testName, userId, event, variantId, eventData?)`
+
+Record an A/B test event.
+
+### React Hooks
+
+#### `useFeatureFlag(flagName, options?)`
+
+React hook for single feature flag.
+
+#### `useFeatureFlags(flagNames, options?)`
+
+React hook for multiple feature flags.
+
+#### `useABTest(testName, options)`
+
+React hook for A/B testing.
+
+### Configuration Options
+
+```typescript
+interface FlipFlagConfig {
+  apiKey: string; // Required: Your API key
+  baseUrl?: string; // Optional: API base URL
+  projectId: string; // Required: Project UUID
+  environment?: string; // Optional: 'dev', 'staging', 'prod'
+  cacheTimeout?: number; // Optional: Cache TTL in ms
+  retryAttempts?: number; // Optional: Number of retry attempts
+  retryDelay?: number; // Optional: Base retry delay in ms
+}
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- 📖 [Documentation](https://docs.flipflag.ru)
+- 💬 [Discord Community](https://discord.gg/flipflag)
+- 🐛 [Issue Tracker](https://github.com/flipflag/flipflag-sdk/issues)
+- 📧 [Email Support](mailto:support@flipflag.ru)
+
+---
+
+Made with ❤️ by the FlipFlag team