@setgo/sdk 1.0.1

package/README.md

@@ -0,0 +1,184 @@
+# @setgo/sdk
+
+SDK oficial do SetGo Feature Flags para Node.js e NestJS.
+
+## Instalacao
+
+```bash
+yarn add @setgo/sdk
+```
+
+## Uso Basico (Node.js)
+
+```typescript
+import { SetGoClient } from '@setgo/sdk';
+
+const client = new SetGoClient({
+  baseUrl: process.env.SETGO_URL,
+  token: process.env.SETGO_TOKEN,
+  appName: 'minha-app',
+});
+
+// Iniciar o cliente (registra e busca features)
+await client.start();
+
+// Verificar se uma feature esta habilitada
+if (client.isEnabled('dark-mode', { userId: '123' })) {
+  // Feature habilitada para este usuario
+}
+
+// Obter uma feature especifica
+const feature = client.getFeature('dark-mode');
+
+// Obter todas as features
+const features = client.getAllFeatures();
+
+// Escutar eventos
+client.on('update', (event) => {
+  console.log('Features atualizadas:', event.features);
+});
+
+client.on('error', (event) => {
+  console.error('Erro:', event.error);
+});
+
+// Parar o cliente (envia metricas pendentes)
+await client.stop();
+```
+
+## Uso com NestJS
+
+### Configuracao do Modulo
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { SetGoModule } from '@setgo/sdk/nestjs';
+
+@Module({
+  imports: [
+    SetGoModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        baseUrl: config.get('SETGO_URL'),
+        token: config.get('SETGO_TOKEN'),
+        appName: config.get('APP_NAME'),
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Usando o Service
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { SetGoService } from '@setgo/sdk/nestjs';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly setgo: SetGoService) {}
+
+  async doSomething(userId: string) {
+    if (this.setgo.isEnabled('new-feature', { userId })) {
+      // Feature habilitada
+    }
+  }
+}
+```
+
+## Configuracao
+
+| Opcao | Tipo | Padrao | Descricao |
+|-------|------|--------|-----------|
+| `baseUrl` | string | **obrigatorio** | URL da API do SetGo |
+| `token` | string | **obrigatorio** | Token de API do cliente |
+| `appName` | string | **obrigatorio** | Nome da aplicacao |
+| `environment` | string | - | Ambiente (geralmente definido no token) |
+| `instanceId` | string | auto-gerado | Identificador unico da instancia |
+| `refreshInterval` | number | 15000 | Intervalo de polling em ms |
+| `metricsInterval` | number | 60000 | Intervalo de envio de metricas em ms |
+| `timeout` | number | 10000 | Timeout das requisicoes em ms |
+| `disableMetrics` | boolean | false | Desabilitar coleta de metricas |
+
+## Contexto de Avaliacao
+
+Ao avaliar uma feature, voce pode passar um contexto:
+
+```typescript
+client.isEnabled('feature-name', {
+  userId: '123',              // ID do usuario
+  sessionId: 'abc',           // ID da sessao
+  remoteAddress: '192.168.1.1', // IP do cliente
+  properties: {               // Propriedades customizadas
+    plan: 'premium',
+    country: 'BR',
+  },
+});
+```
+
+## Estrategias Suportadas
+
+O SDK avalia as seguintes estrategias localmente:
+
+- **DEFAULT**: Feature habilitada/desabilitada globalmente
+- **GRADUAL_ROLLOUT**: Rollout gradual baseado em porcentagem
+- **USER_WITH_ID**: Habilita para usuarios especificos
+- **FLEXIBLE_ROLLOUT**: Rollout com stickiness customizado
+- **REMOTE_ADDRESS**: Habilita para IPs/CIDRs especificos
+
+## Eventos
+
+```typescript
+// Quando o cliente esta pronto
+client.on('ready', (event) => {
+  console.log('Pronto com', event.features.length, 'features');
+});
+
+// Quando features sao atualizadas
+client.on('update', (event) => {
+  console.log('Versao', event.version, 'com', event.features.length, 'features');
+});
+
+// Quando ocorre um erro
+client.on('error', (event) => {
+  console.error('Erro:', event.error);
+});
+```
+
+## Tratamento de Erros
+
+```typescript
+import { SetGoError, NetworkError, AuthenticationError, TimeoutError } from '@setgo/sdk';
+
+try {
+  await client.start();
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // Token invalido
+  } else if (error instanceof NetworkError) {
+    // Erro de rede
+  } else if (error instanceof TimeoutError) {
+    // Timeout
+  }
+}
+```
+
+## Metricas
+
+O SDK coleta automaticamente metricas de uso (quantas vezes cada feature foi avaliada como true/false) e envia para a API em intervalos regulares. As metricas sao agregadas por hora.
+
+Para desabilitar:
+
+```typescript
+const client = new SetGoClient({
+  // ...
+  disableMetrics: true,
+});
+```
+
+## Licenca
+
+UNLICENSED - Uso interno apenas.

package/dist/core/client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * SetGo Client - main SDK entry point
+ */
+import type { SetGoConfig, Feature, FeatureContext, SetGoEventType, SetGoEventHandler } from '../types/index.js';
+export declare class SetGoClient {
+    private config;
+    private repository;
+    private metricsReporter;
+    private evaluator;
+    private pollInterval?;
+    private etag?;
+    private ready;
+    private started;
+    private events;
+    constructor(config: SetGoConfig);
+    /**
+     * Validate configuration
+     */
+    private validateConfig;
+    /**
+     * Generate a unique instance ID
+     */
+    private generateInstanceId;
+    /**
+     * Start the client - registers with API and starts polling
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the client - stops polling and flushes metrics
+     */
+    stop(): Promise<void>;
+    /**
+     * Register client with the server
+     */
+    private register;
+    /**
+     * Start polling for feature updates
+     */
+    private startPolling;
+    /**
+     * Fetch features from the API
+     */
+    private fetchFeatures;
+    /**
+     * Make an HTTP request
+     */
+    private makeRequest;
+    /**
+     * Check if a feature is enabled
+     */
+    isEnabled(featureName: string, context?: FeatureContext): boolean;
+    /**
+     * Evaluate a feature's strategies
+     */
+    private evaluateFeature;
+    /**
+     * Get a feature by name
+     */
+    getFeature(featureName: string): Feature | undefined;
+    /**
+     * Get all features
+     */
+    getAllFeatures(): Feature[];
+    /**
+     * Check if client is ready
+     */
+    isReady(): boolean;
+    /**
+     * Subscribe to an event
+     */
+    on<T extends SetGoEventType>(event: T, handler: SetGoEventHandler<T>): void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<T extends SetGoEventType>(event: T, handler: SetGoEventHandler<T>): void;
+    /**
+     * Emit an event
+     */
+    private emit;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,WAAW,EAEX,OAAO,EACP,cAAc,EAEd,cAAc,EACd,iBAAiB,EAKlB,MAAM,mBAAmB,CAAC;AAa3B,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,YAAY,CAAC,CAAiC;IACtD,OAAO,CAAC,IAAI,CAAC,CAAS;IACtB,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,MAAM,CAA0E;gBAE5E,MAAM,EAAE,WAAW;IAyB/B;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B;;OAEG;YACW,QAAQ;IAoBtB;;OAEG;IACH,OAAO,CAAC,YAAY;IAgBpB;;OAEG;YACW,aAAa;IAwC3B;;OAEG;YACW,WAAW;IA2DzB;;OAEG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO;IAqBjE;;OAEG;IACH,OAAO,CAAC,eAAe;IAmBvB;;OAEG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIpD;;OAEG;IACH,cAAc,IAAI,OAAO,EAAE;IAI3B;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI;IAO3E;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI;IAO5E;;OAEG;IACH,OAAO,CAAC,IAAI;CAkBb"}

package/dist/core/client.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * SetGo Client - main SDK entry point
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SetGoClient = void 0;
+const repository_js_1 = require("./repository.js");
+const metrics_reporter_js_1 = require("./metrics-reporter.js");
+const strategy_evaluator_js_1 = require("./strategy-evaluator.js");
+const index_js_1 = require("../errors/index.js");
+const SDK_VERSION = '1.0.0';
+class SetGoClient {
+    config;
+    repository;
+    metricsReporter;
+    evaluator;
+    pollInterval;
+    etag;
+    ready = false;
+    started = false;
+    events = new Map();
+    constructor(config) {
+        this.validateConfig(config);
+        this.config = {
+            baseUrl: config.baseUrl.replace(/\/$/, ''), // Remove trailing slash
+            token: config.token,
+            appName: config.appName,
+            environment: config.environment,
+            instanceId: config.instanceId ?? this.generateInstanceId(),
+            refreshInterval: config.refreshInterval ?? 15000,
+            metricsInterval: config.metricsInterval ?? 60000,
+            timeout: config.timeout ?? 10000,
+            disableMetrics: config.disableMetrics ?? false,
+        };
+        this.repository = new repository_js_1.FeatureRepository();
+        this.metricsReporter = new metrics_reporter_js_1.MetricsReporter(this.config);
+        this.evaluator = new strategy_evaluator_js_1.StrategyEvaluator();
+        // Initialize event maps
+        this.events.set('ready', new Set());
+        this.events.set('update', new Set());
+        this.events.set('error', new Set());
+    }
+    /**
+     * Validate configuration
+     */
+    validateConfig(config) {
+        if (!config.baseUrl) {
+            throw new index_js_1.ConfigurationError('baseUrl is required');
+        }
+        if (!config.token) {
+            throw new index_js_1.ConfigurationError('token is required');
+        }
+        if (!config.appName) {
+            throw new index_js_1.ConfigurationError('appName is required');
+        }
+    }
+    /**
+     * Generate a unique instance ID
+     */
+    generateInstanceId() {
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+    /**
+     * Start the client - registers with API and starts polling
+     */
+    async start() {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        try {
+            // Register client with the server
+            await this.register();
+            // Initial feature fetch
+            await this.fetchFeatures();
+            // Mark as ready
+            this.ready = true;
+            // Emit ready event
+            this.emit('ready', {
+                type: 'ready',
+                features: this.repository.getAll(),
+            });
+            // Start polling
+            this.startPolling();
+            // Start metrics reporting
+            this.metricsReporter.start();
+        }
+        catch (error) {
+            this.started = false;
+            this.emit('error', {
+                type: 'error',
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Stop the client - stops polling and flushes metrics
+     */
+    async stop() {
+        if (!this.started) {
+            return;
+        }
+        // Stop polling
+        if (this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = undefined;
+        }
+        // Flush remaining metrics
+        await this.metricsReporter.flush();
+        this.metricsReporter.stop();
+        this.started = false;
+        this.ready = false;
+    }
+    /**
+     * Register client with the server
+     */
+    async register() {
+        const url = `${this.config.baseUrl}/client/register`;
+        const payload = {
+            appName: this.config.appName,
+            instanceId: this.config.instanceId,
+            sdkVersion: SDK_VERSION,
+            platformInfo: {
+                nodeVersion: typeof process !== 'undefined' ? process.version : 'unknown',
+                platform: typeof process !== 'undefined' ? process.platform : 'unknown',
+            },
+            interval: this.config.refreshInterval,
+        };
+        await this.makeRequest(url, {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+    }
+    /**
+     * Start polling for feature updates
+     */
+    startPolling() {
+        this.pollInterval = setInterval(() => {
+            void this.fetchFeatures().catch((error) => {
+                this.emit('error', {
+                    type: 'error',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            });
+        }, this.config.refreshInterval);
+        // Ensure the interval doesn't prevent Node.js from exiting
+        if (this.pollInterval.unref) {
+            this.pollInterval.unref();
+        }
+    }
+    /**
+     * Fetch features from the API
+     */
+    async fetchFeatures() {
+        const url = `${this.config.baseUrl}/client/features`;
+        const headers = {};
+        if (this.etag) {
+            headers['If-None-Match'] = this.etag;
+        }
+        const response = await this.makeRequest(url, {
+            method: 'GET',
+            headers,
+            expectNotModified: true,
+        });
+        // 304 Not Modified - no changes
+        if (response.status === 304) {
+            return;
+        }
+        const data = (await response.json());
+        const previousVersion = this.repository.getVersion();
+        this.repository.update(data);
+        // Update etag
+        const newEtag = response.headers.get('etag');
+        if (newEtag) {
+            this.etag = newEtag;
+        }
+        // Emit update event if version changed and client was already ready
+        if (this.ready && data.version !== previousVersion) {
+            this.emit('update', {
+                type: 'update',
+                features: this.repository.getAll(),
+                version: data.version,
+            });
+        }
+    }
+    /**
+     * Make an HTTP request
+     */
+    async makeRequest(url, options) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: options.method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: this.config.token,
+                    ...options.headers,
+                },
+                body: options.body,
+                signal: controller.signal,
+            });
+            // Handle 304 Not Modified
+            if (options.expectNotModified && response.status === 304) {
+                return response;
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new index_js_1.AuthenticationError();
+            }
+            if (!response.ok) {
+                throw new index_js_1.NetworkError(`Request failed: ${response.statusText}`, response.status);
+            }
+            return response;
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new index_js_1.TimeoutError();
+            }
+            if (error instanceof index_js_1.NetworkError ||
+                error instanceof index_js_1.AuthenticationError ||
+                error instanceof index_js_1.TimeoutError) {
+                throw error;
+            }
+            throw new index_js_1.NetworkError(`Request failed: ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, error instanceof Error ? error : undefined);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Check if a feature is enabled
+     */
+    isEnabled(featureName, context) {
+        const feature = this.repository.get(featureName);
+        if (!feature) {
+            // Unknown feature - return false
+            this.metricsReporter.track(featureName, false);
+            return false;
+        }
+        if (!feature.enabled) {
+            // Feature is globally disabled
+            this.metricsReporter.track(featureName, false);
+            return false;
+        }
+        // Evaluate strategies
+        const enabled = this.evaluateFeature(feature, context);
+        this.metricsReporter.track(featureName, enabled);
+        return enabled;
+    }
+    /**
+     * Evaluate a feature's strategies
+     */
+    evaluateFeature(feature, context) {
+        if (!feature.strategies || feature.strategies.length === 0) {
+            // No strategies - return the feature's enabled status
+            return feature.enabled;
+        }
+        // Strategies are evaluated in order (by sortOrder)
+        // First matching enabled strategy wins
+        const sortedStrategies = [...feature.strategies].sort((a, b) => a.sortOrder - b.sortOrder);
+        for (const strategy of sortedStrategies) {
+            if (this.evaluator.evaluate(strategy, context)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Get a feature by name
+     */
+    getFeature(featureName) {
+        return this.repository.get(featureName);
+    }
+    /**
+     * Get all features
+     */
+    getAllFeatures() {
+        return this.repository.getAll();
+    }
+    /**
+     * Check if client is ready
+     */
+    isReady() {
+        return this.ready;
+    }
+    /**
+     * Subscribe to an event
+     */
+    on(event, handler) {
+        const handlers = this.events.get(event);
+        if (handlers) {
+            handlers.add(handler);
+        }
+    }
+    /**
+     * Unsubscribe from an event
+     */
+    off(event, handler) {
+        const handlers = this.events.get(event);
+        if (handlers) {
+            handlers.delete(handler);
+        }
+    }
+    emit(event, data) {
+        const handlers = this.events.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(data);
+                }
+                catch {
+                    // Ignore handler errors
+                }
+            }
+        }
+    }
+}
+exports.SetGoClient = SetGoClient;

package/dist/core/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SetGo SDK Core - Re-exports
+ */
+export { SetGoClient } from './client.js';
+export { FeatureRepository } from './repository.js';
+export { StrategyEvaluator } from './strategy-evaluator.js';
+export { MetricsReporter } from './metrics-reporter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * SetGo SDK Core - Re-exports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsReporter = exports.StrategyEvaluator = exports.FeatureRepository = exports.SetGoClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "SetGoClient", { enumerable: true, get: function () { return client_js_1.SetGoClient; } });
+var repository_js_1 = require("./repository.js");
+Object.defineProperty(exports, "FeatureRepository", { enumerable: true, get: function () { return repository_js_1.FeatureRepository; } });
+var strategy_evaluator_js_1 = require("./strategy-evaluator.js");
+Object.defineProperty(exports, "StrategyEvaluator", { enumerable: true, get: function () { return strategy_evaluator_js_1.StrategyEvaluator; } });
+var metrics_reporter_js_1 = require("./metrics-reporter.js");
+Object.defineProperty(exports, "MetricsReporter", { enumerable: true, get: function () { return metrics_reporter_js_1.MetricsReporter; } });

package/dist/core/metrics-reporter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Metrics Reporter - collects and sends usage metrics
+ */
+import type { ResolvedSetGoConfig } from '../types/index.js';
+export declare class MetricsReporter {
+    private metrics;
+    private bucketStart;
+    private sendInterval?;
+    private config;
+    constructor(config: ResolvedSetGoConfig);
+    /**
+     * Get the current hour bucket timestamp
+     */
+    private getCurrentHourBucket;
+    /**
+     * Start the metrics reporting interval
+     */
+    start(): void;
+    /**
+     * Stop the metrics reporting interval
+     */
+    stop(): void;
+    /**
+     * Track a feature evaluation
+     */
+    track(featureName: string, enabled: boolean): void;
+    /**
+     * Flush metrics to the server
+     */
+    flush(): Promise<void>;
+    /**
+     * Send metrics to the API
+     */
+    private sendMetrics;
+    /**
+     * Get current metrics count (for testing/debugging)
+     */
+    getMetricsCount(): number;
+}
+//# sourceMappingURL=metrics-reporter.d.ts.map

package/dist/core/metrics-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-reporter.d.ts","sourceRoot":"","sources":["../../src/core/metrics-reporter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAiC,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAQ5F,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAA6C;IAC5D,OAAO,CAAC,WAAW,CAAO;IAC1B,OAAO,CAAC,YAAY,CAAC,CAAiC;IACtD,OAAO,CAAC,MAAM,CAAsB;gBAExB,MAAM,EAAE,mBAAmB;IAKvC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACH,IAAI,IAAI,IAAI;IAOZ;;OAEG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAsBlD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC5B;;OAEG;YACW,WAAW;IAqCzB;;OAEG;IACH,eAAe,IAAI,MAAM;CAG1B"}