@savvagent/angular 1.0.1

package/dist/module.d.ts

@@ -0,0 +1,57 @@
+import { ModuleWithProviders } from '@angular/core';
+import { SavvagentConfig } from './service';
+import * as i0 from "@angular/core";
+/**
+ * Angular module for Savvagent feature flags.
+ *
+ * @example
+ * ```typescript
+ * // app.module.ts
+ * import { SavvagentModule } from '@savvagent/angular';
+ *
+ * @NgModule({
+ *   imports: [
+ *     SavvagentModule.forRoot({
+ *       config: {
+ *         apiKey: 'sdk_your_api_key',
+ *         baseUrl: 'https://api.savvagent.com'
+ *       },
+ *       defaultContext: {
+ *         applicationId: 'my-app',
+ *         environment: 'production',
+ *         userId: 'user-123'
+ *       }
+ *     })
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // For standalone components (Angular 14+)
+ * import { SavvagentModule } from '@savvagent/angular';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     importProvidersFrom(
+ *       SavvagentModule.forRoot({
+ *         config: { apiKey: 'sdk_...' }
+ *       })
+ *     )
+ *   ]
+ * });
+ * ```
+ */
+export declare class SavvagentModule {
+    /**
+     * Configure the Savvagent module with API key and default context.
+     *
+     * @param savvagentConfig - Configuration including API key and optional default context
+     * @returns Module with providers
+     */
+    static forRoot(savvagentConfig: SavvagentConfig): ModuleWithProviders<SavvagentModule>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SavvagentModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<SavvagentModule, never, never, never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<SavvagentModule>;
+}

package/dist/service.d.ts

@@ -0,0 +1,319 @@
+import { OnDestroy, InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { FlagClient, FlagClientConfig, FlagContext, FlagEvaluationResult, FlagDefinition } from '@savvagent/sdk';
+import * as i0 from "@angular/core";
+/**
+ * Default context values that apply to all flag evaluations
+ * Per SDK Developer Guide: https://docs.savvagent.com/sdk-developer-guide
+ */
+export interface DefaultFlagContext {
+    /** Application ID for application-scoped flags */
+    applicationId?: string;
+    /** Environment (development, staging, production) */
+    environment?: string;
+    /** Organization ID for multi-tenant apps */
+    organizationId?: string;
+    /** Default user ID (required for percentage rollouts) */
+    userId?: string;
+    /** Default anonymous ID (alternative to userId for anonymous users) */
+    anonymousId?: string;
+    /** Session ID as fallback identifier */
+    sessionId?: string;
+    /** User's language code (e.g., "en", "es") */
+    language?: string;
+    /** Default attributes for targeting */
+    attributes?: Record<string, any>;
+}
+/**
+ * Configuration for the Savvagent Angular service
+ */
+export interface SavvagentConfig {
+    /** SDK API key configuration */
+    config: FlagClientConfig;
+    /** Default context values applied to all flag evaluations */
+    defaultContext?: DefaultFlagContext;
+}
+/**
+ * Injection token for Savvagent configuration
+ */
+export declare const SAVVAGENT_CONFIG: InjectionToken<SavvagentConfig>;
+/**
+ * Result from flag evaluation as an Observable
+ */
+export interface FlagObservableResult {
+    /** Current flag value */
+    value: boolean;
+    /** Whether the flag is currently being evaluated */
+    loading: boolean;
+    /** Error if evaluation failed */
+    error: Error | null;
+    /** Detailed evaluation result */
+    result: FlagEvaluationResult | null;
+}
+/**
+ * Options for flag evaluation
+ */
+export interface FlagOptions {
+    /** Context for flag evaluation (user_id, attributes, etc.) */
+    context?: FlagContext;
+    /** Default value to use while loading or on error */
+    defaultValue?: boolean;
+    /** Enable real-time updates for this flag */
+    realtime?: boolean;
+}
+/**
+ * Angular service for Savvagent feature flags.
+ * Provides reactive flag evaluation using RxJS Observables.
+ *
+ * @example
+ * ```typescript
+ * // In your component
+ * @Component({...})
+ * export class MyComponent {
+ *   newFeature$ = this.savvagent.flag$('new-feature');
+ *
+ *   constructor(private savvagent: SavvagentService) {}
+ * }
+ *
+ * // In your template
+ * <div *ngIf="(newFeature$ | async)?.value">
+ *   New feature content!
+ * </div>
+ * ```
+ */
+export declare class SavvagentService implements OnDestroy {
+    private client;
+    private destroy$;
+    private isReady$;
+    private defaultContext;
+    private flagSubjects;
+    constructor(config?: SavvagentConfig);
+    /**
+     * Initialize the Savvagent client with configuration.
+     * Call this if not using the SAVVAGENT_CONFIG injection token.
+     *
+     * @param savvagentConfig - Configuration including API key and default context
+     *
+     * @example
+     * ```typescript
+     * @Component({...})
+     * export class AppComponent implements OnInit {
+     *   constructor(private savvagent: SavvagentService) {}
+     *
+     *   ngOnInit() {
+     *     this.savvagent.initialize({
+     *       config: { apiKey: 'sdk_...' },
+     *       defaultContext: {
+     *         applicationId: 'my-app',
+     *         environment: 'development',
+     *         userId: 'user-123'
+     *       }
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    initialize(savvagentConfig: SavvagentConfig): void;
+    /**
+     * Observable that emits true when the client is ready.
+     */
+    get ready$(): Observable<boolean>;
+    /**
+     * Check if the client is ready.
+     */
+    get isReady(): boolean;
+    /**
+     * Get the underlying FlagClient instance for advanced use cases.
+     */
+    get flagClient(): FlagClient | null;
+    /**
+     * Merge default context with per-call context.
+     */
+    private mergeContext;
+    /**
+     * Get a reactive Observable for a feature flag.
+     * Automatically updates when the flag value changes.
+     *
+     * @param flagKey - The feature flag key to evaluate
+     * @param options - Configuration options
+     * @returns Observable of flag evaluation state
+     *
+     * @example
+     * ```typescript
+     * // In your component
+     * newFeature$ = this.savvagent.flag$('new-feature', {
+     *   defaultValue: false,
+     *   realtime: true,
+     *   context: { attributes: { plan: 'pro' } }
+     * });
+     *
+     * // In template
+     * <ng-container *ngIf="newFeature$ | async as flag">
+     *   <app-loading *ngIf="flag.loading"></app-loading>
+     *   <app-new-feature *ngIf="flag.value"></app-new-feature>
+     *   <app-old-feature *ngIf="!flag.value && !flag.loading"></app-old-feature>
+     * </ng-container>
+     * ```
+     */
+    flag$(flagKey: string, options?: FlagOptions): Observable<FlagObservableResult>;
+    /**
+     * Generate a cache key for a flag+context combination.
+     */
+    private getCacheKey;
+    /**
+     * Evaluate a flag and emit the result to a subject.
+     */
+    private evaluateAndEmit;
+    /**
+     * Re-evaluate all active flag subscriptions.
+     * Called when overrides change.
+     */
+    private reEvaluateAllFlags;
+    /**
+     * Get a flag value as a simple Observable<boolean>.
+     * Useful when you only need the value without loading/error states.
+     *
+     * @param flagKey - The feature flag key to evaluate
+     * @param options - Configuration options
+     * @returns Observable of boolean flag value
+     *
+     * @example
+     * ```typescript
+     * isFeatureEnabled$ = this.savvagent.flagValue$('my-feature');
+     *
+     * // In template
+     * <button *ngIf="isFeatureEnabled$ | async">New Button</button>
+     * ```
+     */
+    flagValue$(flagKey: string, options?: FlagOptions): Observable<boolean>;
+    /**
+     * Evaluate a feature flag once (non-reactive).
+     * For reactive updates, use flag$() instead.
+     *
+     * @param flagKey - The feature flag key to evaluate
+     * @param context - Optional context for targeting
+     * @returns Promise with detailed evaluation result
+     *
+     * @example
+     * ```typescript
+     * async checkFeature() {
+     *   const result = await this.savvagent.evaluate('new-feature');
+     *   if (result.value) {
+     *     // Feature is enabled
+     *   }
+     * }
+     * ```
+     */
+    evaluate(flagKey: string, context?: FlagContext): Promise<FlagEvaluationResult>;
+    /**
+     * Check if a feature flag is enabled (non-reactive).
+     *
+     * @param flagKey - The feature flag key to evaluate
+     * @param context - Optional context for targeting
+     * @returns Promise<boolean>
+     */
+    isEnabled(flagKey: string, context?: FlagContext): Promise<boolean>;
+    /**
+     * Execute code conditionally based on flag value.
+     *
+     * @param flagKey - The flag key to check
+     * @param callback - Function to execute if flag is enabled
+     * @param context - Optional context for targeting
+     *
+     * @example
+     * ```typescript
+     * await this.savvagent.withFlag('analytics-enabled', async () => {
+     *   await this.analytics.track('page_view');
+     * });
+     * ```
+     */
+    withFlag<T>(flagKey: string, callback: () => T | Promise<T>, context?: FlagContext): Promise<T | null>;
+    /**
+     * Track an error with flag context.
+     *
+     * @param flagKey - The flag key associated with the error
+     * @param error - The error that occurred
+     * @param context - Optional context
+     */
+    trackError(flagKey: string, error: Error, context?: FlagContext): void;
+    /**
+     * Set the user ID for logged-in users.
+     *
+     * @param userId - The user ID (or null to clear)
+     */
+    setUserId(userId: string | null): void;
+    /**
+     * Get the current user ID.
+     */
+    getUserId(): string | null;
+    /**
+     * Get the current anonymous ID.
+     */
+    getAnonymousId(): string | null;
+    /**
+     * Set a custom anonymous ID.
+     */
+    setAnonymousId(id: string): void;
+    /**
+     * Set a local override for a flag.
+     * Overrides take precedence over server values.
+     *
+     * @param flagKey - The flag key to override
+     * @param value - The override value
+     */
+    setOverride(flagKey: string, value: boolean): void;
+    /**
+     * Clear a local override for a flag.
+     */
+    clearOverride(flagKey: string): void;
+    /**
+     * Clear all local overrides.
+     */
+    clearAllOverrides(): void;
+    /**
+     * Check if a flag has a local override.
+     */
+    hasOverride(flagKey: string): boolean;
+    /**
+     * Get the override value for a flag.
+     */
+    getOverride(flagKey: string): boolean | undefined;
+    /**
+     * Get all current overrides.
+     */
+    getOverrides(): Record<string, boolean>;
+    /**
+     * Set multiple overrides at once.
+     */
+    setOverrides(overrides: Record<string, boolean>): void;
+    /**
+     * Get all flags for the application.
+     *
+     * @param environment - Environment to evaluate (default: 'development')
+     * @returns Observable of flag definitions
+     */
+    getAllFlags$(environment?: string): Observable<FlagDefinition[]>;
+    /**
+     * Get all flags for the application (Promise-based).
+     */
+    getAllFlags(environment?: string): Promise<FlagDefinition[]>;
+    /**
+     * Get enterprise-scoped flags only.
+     */
+    getEnterpriseFlags(environment?: string): Promise<FlagDefinition[]>;
+    /**
+     * Clear the flag cache.
+     */
+    clearCache(): void;
+    /**
+     * Check if real-time connection is active.
+     */
+    isRealtimeConnected(): boolean;
+    /**
+     * Close the client and cleanup resources.
+     */
+    close(): void;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SavvagentService, [{ optional: true; }]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SavvagentService>;
+}

package/jest.config.js

@@ -0,0 +1,40 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/*.spec.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/index.ts'
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  moduleNameMapper: {
+    '^@savvagent/sdk$': '<rootDir>/../typescript/src/index.ts',
+    '^@angular/core/testing$': '<rootDir>/test-utils/angular-testing-mock.ts',
+    '^@angular/core$': '<rootDir>/test-utils/angular-core-mock.ts',
+  },
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig: {
+        target: 'ES2022',
+        module: 'CommonJS',
+        lib: ['ES2022', 'DOM'],
+        esModuleInterop: true,
+        skipLibCheck: true,
+        experimentalDecorators: true,
+        emitDecoratorMetadata: true,
+        useDefineForClassFields: false,
+        moduleResolution: 'node',
+        noUnusedLocals: false,
+        noUnusedParameters: false,
+      },
+    }],
+  },
+  transformIgnorePatterns: [
+    'node_modules/(?!(@angular|rxjs|tslib)/)'
+  ],
+  extensionsToTreatAsEsm: ['.ts'],
+};

package/ng-package.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "dist",
+  "lib": {
+    "entryFile": "src/index.ts"
+  },
+  "allowedNonPeerDependencies": ["@savvagent/sdk", "tslib"]
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@savvagent/angular",
+  "version": "1.0.1",
+  "description": "Angular SDK for Savvagent feature flags",
+  "author": "Savvagent",
+  "license": "MIT",
+  "main": "./dist/fesm2022/savvagent-angular.mjs",
+  "module": "./dist/fesm2022/savvagent-angular.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "esm2022": "./dist/esm2022/savvagent-angular.mjs",
+      "esm": "./dist/esm2022/savvagent-angular.mjs",
+      "default": "./dist/fesm2022/savvagent-angular.mjs"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "peerDependencies": {
+    "@angular/common": ">=14.0.0",
+    "@angular/core": ">=14.0.0",
+    "rxjs": ">=7.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1",
+    "@savvagent/sdk": "1.0.1"
+  },
+  "devDependencies": {
+    "@angular/common": "^18.2.14",
+    "@angular/compiler": "^18.2.14",
+    "@angular/compiler-cli": "^18.2.14",
+    "@angular/core": "^18.2.14",
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "30.2.0",
+    "jest-preset-angular": "15.0.3",
+    "ng-packagr": "^18.2.1",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "^7.8.2",
+    "ts-jest": "29.4.5",
+    "ts-node": "^10.9.2",
+    "typescript": "~5.4.5"
+  },
+  "keywords": [
+    "savvagent",
+    "feature-flags",
+    "angular",
+    "service",
+    "feature-toggles"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/savvagent/savvagent-sdks",
+    "directory": "packages/angular"
+  },
+  "bugs": {
+    "url": "https://github.com/savvagent/savvagent-sdks/issues"
+  },
+  "homepage": "https://github.com/savvagent/savvagent-sdks/tree/main/packages/angular#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "dev": "ng-packagr -p ng-package.json --watch",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\""
+  }
+}

package/setup-jest.ts

@@ -0,0 +1,2 @@
+// Jest setup file
+import 'reflect-metadata';

package/src/index.spec.ts

@@ -0,0 +1,144 @@
+/**
+ * Integration tests for package exports
+ */
+
+import * as AngularSDK from './index';
+
+describe('Package Exports', () => {
+  describe('Module Exports', () => {
+    it('should export SavvagentModule', () => {
+      expect(AngularSDK.SavvagentModule).toBeDefined();
+      expect(typeof AngularSDK.SavvagentModule).toBe('function');
+    });
+  });
+
+  describe('Service Exports', () => {
+    it('should export SavvagentService', () => {
+      expect(AngularSDK.SavvagentService).toBeDefined();
+      expect(typeof AngularSDK.SavvagentService).toBe('function');
+    });
+
+    it('should export SAVVAGENT_CONFIG injection token', () => {
+      expect(AngularSDK.SAVVAGENT_CONFIG).toBeDefined();
+    });
+  });
+
+  describe('Type Exports', () => {
+    it('should have correct type structure for SavvagentConfig', () => {
+      const config: AngularSDK.SavvagentConfig = {
+        config: {
+          apiKey: 'test',
+        },
+        defaultContext: {
+          applicationId: 'test-app',
+        },
+      };
+      expect(config).toBeDefined();
+    });
+
+    it('should have correct type structure for DefaultFlagContext', () => {
+      const context: AngularSDK.DefaultFlagContext = {
+        applicationId: 'app',
+        environment: 'production',
+        userId: 'user-123',
+        attributes: { plan: 'pro' },
+      };
+      expect(context).toBeDefined();
+    });
+
+    it('should have correct type structure for FlagObservableResult', () => {
+      const result: AngularSDK.FlagObservableResult = {
+        value: true,
+        loading: false,
+        error: null,
+        result: {
+          key: 'test-flag',
+          value: true,
+          reason: 'evaluated',
+        },
+      };
+      expect(result).toBeDefined();
+    });
+
+    it('should have correct type structure for FlagOptions', () => {
+      const options: AngularSDK.FlagOptions = {
+        context: { user_id: 'user-123' },
+        defaultValue: false,
+        realtime: true,
+      };
+      expect(options).toBeDefined();
+    });
+  });
+
+  describe('Re-exported Types from @savvagent/sdk', () => {
+    it('should re-export FlagClient', () => {
+      expect(AngularSDK.FlagClient).toBeDefined();
+      expect(typeof AngularSDK.FlagClient).toBe('function');
+    });
+
+    // Type existence checks - these ensure types are exported
+    it('should provide FlagClientConfig type', () => {
+      const config: AngularSDK.FlagClientConfig = {
+        apiKey: 'test',
+      };
+      expect(config).toBeDefined();
+    });
+
+    it('should provide FlagContext type', () => {
+      const context: AngularSDK.FlagContext = {
+        user_id: 'user-123',
+        attributes: { key: 'value' },
+      };
+      expect(context).toBeDefined();
+    });
+
+    it('should provide FlagEvaluationResult type', () => {
+      const result: AngularSDK.FlagEvaluationResult = {
+        key: 'test-flag',
+        value: true,
+        reason: 'evaluated',
+      };
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('Package Structure', () => {
+    it('should export all documented APIs', () => {
+      const expectedExports = [
+        'SavvagentModule',
+        'SavvagentService',
+        'SAVVAGENT_CONFIG',
+        'FlagClient',
+      ];
+
+      expectedExports.forEach((exportName) => {
+        expect(AngularSDK).toHaveProperty(exportName);
+      });
+    });
+
+    it('should not export internal implementation details', () => {
+      // Ensure we're not accidentally exposing things we shouldn't
+      const internalNames = ['private', 'internal'];
+      const exportKeys = Object.keys(AngularSDK);
+
+      internalNames.forEach((internalName) => {
+        const hasInternal = exportKeys.some((key) =>
+          key.toLowerCase().includes(internalName)
+        );
+        expect(hasInternal).toBe(false);
+      });
+    });
+  });
+
+  describe('Version and Metadata', () => {
+    it('should be a valid package', () => {
+      expect(AngularSDK).toBeDefined();
+      expect(typeof AngularSDK).toBe('object');
+    });
+
+    it('should have non-empty exports', () => {
+      const exportKeys = Object.keys(AngularSDK);
+      expect(exportKeys.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @savvagent/angular - Angular SDK for Savvagent feature flags
+ *
+ * This package provides Angular services and modules for easy integration
+ * of Savvagent feature flags into Angular applications.
+ *
+ * @packageDocumentation
+ */
+
+// Module
+export { SavvagentModule } from './module';
+
+// Service and types
+export { SavvagentService, SAVVAGENT_CONFIG } from './service';
+export type {
+  SavvagentConfig,
+  DefaultFlagContext,
+  FlagObservableResult,
+  FlagOptions,
+} from './service';
+
+// Re-export types from core SDK
+export type {
+  FlagClientConfig,
+  FlagContext,
+  FlagEvaluationResult,
+  EvaluationEvent,
+  ErrorEvent,
+  FlagUpdateEvent,
+  FlagDefinition,
+  FlagListResponse,
+  // Generated API types for advanced users
+  ApiTypes,
+  components,
+} from '@savvagent/sdk';
+
+// Re-export FlagClient for advanced use cases
+export { FlagClient } from '@savvagent/sdk';