myfflags-sdk/README.md

SDK cliente para o SaaS de My F* Flags

# My F* Flags SDK

SDK JavaScript/TypeScript para consumir feature flags do sistema My F* Flags.

## 🚀 Instalação

```bash
npm install @myfflags/sdk
# ou
yarn add @myfflags/sdk
```

## 📖 Uso Básico

```typescript
import FeatureFlagsSDK from '@myfflags/sdk'

// Configurar o SDK
const flagsSDK = new FeatureFlagsSDK({
  apiUrl: 'https://api.myfflags.com',
  apiKey: 'your-api-key', // opcional para APIs privadas
  environment: 'production', // 'dev' | 'staging' | 'production'
  cacheTimeout: 5 * 60 * 1000 // 5 minutos (opcional)
})

// Verificar se uma flag está habilitada
const userContext = {
  userId: 'user-123',
  email: 'user@example.com',
  plan: 'premium',
  country: 'BR'
}

const isNewCheckoutEnabled = await flagsSDK.isFeatureEnabled('new-checkout', userContext)

if (isNewCheckoutEnabled) {
  // Mostrar novo checkout
  console.log('🎉 Novo checkout habilitado!')
} else {
  // Mostrar checkout antigo
  console.log('📦 Checkout padrão')
}
```

## 🎯 Exemplos Avançados

### React Hook

```typescript
import { useState, useEffect } from 'react'
import FeatureFlagsSDK from '@myfflags/sdk'

const flagsSDK = new FeatureFlagsSDK({
  apiUrl: process.env.REACT_APP_FLAGS_API_URL!,
  environment: process.env.REACT_APP_ENVIRONMENT as any
})

export function useFeatureFlag(flagName: string, userContext: any) {
  const [isEnabled, setIsEnabled] = useState(false)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    async function checkFlag() {
      try {
        const enabled = await flagsSDK.isFeatureEnabled(flagName, userContext)
        setIsEnabled(enabled)
      } catch (error) {
        console.error('Error checking feature flag:', error)
        setIsEnabled(false)
      } finally {
        setLoading(false)
      }
    }

    checkFlag()
  }, [flagName, userContext])

  return { isEnabled, loading }
}

// Uso no componente:
function MyComponent() {
  const user = { userId: '123', email: 'user@example.com' }
  const { isEnabled, loading } = useFeatureFlag('new-ui', user)

  if (loading) return <div>Loading...</div>
  
  return (
    <div>
      {isEnabled ? <NewUI /> : <OldUI />}
    </div>
  )
}
```

### Next.js Server-Side

```typescript
// pages/api/check-flag.ts
import FeatureFlagsSDK from '@myfflags/sdk'

const flagsSDK = new FeatureFlagsSDK({
  apiUrl: process.env.FLAGS_API_URL!,
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'dev'
})

export default async function handler(req: any, res: any) {
  const { flagName, userId } = req.query
  
  const isEnabled = await flagsSDK.isFeatureEnabled(flagName, { userId })
  
  res.json({ enabled: isEnabled })
}
```

### Node.js Backend

```typescript
import express from 'express'
import FeatureFlagsSDK from '@myfflags/sdk'

const app = express()
const flagsSDK = new FeatureFlagsSDK({
  apiUrl: process.env.FLAGS_API_URL!,
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'dev'
})

app.get('/api/users/:userId/features', async (req, res) => {
  const { userId } = req.params
  const userContext = { userId, email: req.user?.email }
  
  const enabledFeatures = await flagsSDK.getEnabledFeatures(userContext)
  
  res.json({ features: enabledFeatures })
})
```

## 🎛️ API Reference

### `FeatureFlagsSDK`

#### Constructor

```typescript
new FeatureFlagsSDK(config: SDKConfig)
```

**SDKConfig:**
- `apiUrl: string` - URL da API de flags
- `apiKey?: string` - Chave de API (opcional)
- `environment?: 'dev' | 'staging' | 'production'` - Ambiente (padrão: 'production')
- `cacheTimeout?: number` - Timeout do cache em ms (padrão: 5 minutos)

#### Métodos

##### `isFeatureEnabled(flagName: string, userContext: UserContext): Promise<boolean>`

Verifica se uma feature flag específica está habilitada para o usuário.

**Parâmetros:**
- `flagName` - Nome da flag
- `userContext` - Contexto do usuário (userId obrigatório)

**Retorna:** `Promise<boolean>`

##### `getEnabledFeatures(userContext: UserContext): Promise<string[]>`

Busca todas as flags habilitadas para o usuário.

**Retorna:** `Promise<string[]>` - Array com nomes das flags habilitadas

##### `clearCache(): void`

Limpa o cache interno.

##### `updateConfig(newConfig: Partial<SDKConfig>): void`

Atualiza a configuração e limpa o cache.

### `UserContext`

```typescript
interface UserContext {
  userId: string          // Obrigatório
  email?: string         // Para targeting por domínio
  plan?: string          // premium, basic, etc
  country?: string       // BR, US, etc
  [key: string]: any     // Atributos customizados
}
```

## 🎯 Targeting Rules

O SDK suporta regras de targeting baseadas no contexto do usuário:

```typescript
// Exemplos de regras que funcionam:
const userContext = {
  userId: 'user-123',
  email: 'admin@company.com',
  plan: 'premium',
  country: 'BR',
  appVersion: '2.1.0'
}

// Regras possíveis:
// - email contains '@company.com'
// - plan equals 'premium'
// - country not_equals 'US'
// - appVersion greater_than '2.0.0'
```

## 📊 Rollout Percentual

O rollout é determinístico baseado no `userId + flagName`:

```typescript
// Mesmo usuário sempre recebe o mesmo resultado
const user1 = { userId: 'user-123' }

// Se rollout = 50%, user-123 sempre vai receber o mesmo resultado
const enabled1 = await flagsSDK.isFeatureEnabled('new-feature', user1) // true ou false
const enabled2 = await flagsSDK.isFeatureEnabled('new-feature', user1) // mesmo resultado
```

## ⚡ Performance e Cache

- **Cache automático** por 5 minutos (configurável)
- **Fallback** para cache antigo em caso de erro
- **Determinístico** - mesmo input sempre produz mesmo output
- **Rate limiting** respeitado automaticamente

## 🐛 Error Handling

```typescript
try {
  const isEnabled = await flagsSDK.isFeatureEnabled('my-flag', userContext)
  // usar isEnabled
} catch (error) {
  // Em caso de erro, sempre retorna false
  console.error('Flag evaluation failed:', error)
  // Implementar fallback
}
```

## 🔧 Configuração de Ambiente

```bash
# .env
REACT_APP_FLAGS_API_URL=https://api.myfflags.com
REACT_APP_FLAGS_API_KEY=your-api-key
REACT_APP_ENVIRONMENT=production
```

## 📱 Suporte

- ✅ React / React Native
- ✅ Next.js (SSR + Client)
- ✅ Node.js / Express
- ✅ Vue.js / Nuxt.js
- ✅ Vanilla JavaScript
- ✅ TypeScript

## 🚀 Deploy

O SDK funciona em qualquer ambiente JavaScript:

- **Frontend**: Bundlers (Webpack, Vite, Parcel)
- **Backend**: Node.js, Serverless Functions
- **Mobile**: React Native, Expo
- **Edge**: Cloudflare Workers, Vercel Edge

## 📞 Suporte

Para dúvidas ou problemas:
- 📧 Email: support@myfflags.com
- 🐛 Issues: [GitHub Issues](https://github.com/your-org/myfflags/issues)
- 📖 Docs: [Documentação Completa](https://docs.myfflags.com)