@atono-io/server-sdk 1.4.0-rc.2

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/dist/types.d.ts

@@ -0,0 +1,314 @@
+import { Provider } from '@openfeature/server-sdk';
+import { AxiosInstance } from 'axios';
+import { BaseHook, HookContext, EvaluationDetails as EvaluationDetails$1, FlagValue, StandardResolutionReasons, ErrorCode } from '@openfeature/core';
+
+type LocationContext$1 = {
+    continent: string;
+    subcontinent?: string;
+    country?: string;
+    region?: string;
+};
+
+type BaseEvaluationContext = {
+    customer?: string;
+};
+type EvaluationContextPart = {
+    [key: string]: any;
+};
+type EvaluationContext = BaseEvaluationContext & EvaluationContextPart;
+
+declare enum LogLevels {
+    DEBUG = "DEBUG",
+    ERROR = "ERROR",
+    FATAL = "FATAL",
+    INFO = "INFO",
+    TRACE = "TRACE",
+    WARN = "WARN"
+}
+type ConcreteLogger = new (category: string) => Logger;
+type LoggerListener = (entry: StructuredLog) => void;
+type LogElement = Record<string, any> | Error;
+type LoggerConfig = {
+    /**
+     * Log level threshold to display.
+     *
+     * Default: 'INFO'
+     */
+    level?: string;
+    /**
+     * Implementation of the logger. This SDK provides two implementations out of the box:
+     *
+     * - ConsoleLogger: Logs to the console.
+     *
+     * - NoopLogger: Does not output any log events, but can still be used to listen to structured log events.
+     *
+     * Default: ConsoleLogger
+     */
+    implementation?: ConcreteLogger;
+    /**
+     * Hook to listen to structured log events. A log event listener is a function that takes a log entry as an
+     * argument and returns nothing.
+     *
+     * See {@link StructuredLog}
+     *
+     * Default: undefined
+     */
+    onLogEvent?: LoggerListener;
+};
+type StructuredLog = Record<string, any> & {
+    /**
+     * The category of the log indicates it source within the SDK.
+     */
+    category: string;
+    /**
+     * The level of the log.
+     */
+    level: LogLevels;
+    /**
+     * The message of the log.
+     */
+    message?: string;
+    /**
+     * The timestamp when the log was emitted.
+     */
+    timestamp: Date;
+};
+declare abstract class Logger {
+    protected constructor(category: string);
+    protected abstract outputLogEntry(entry: StructuredLog): void;
+    static configure(config: LoggerConfig): void;
+    static getLogger(category: string): Logger;
+    trace(message: any, context?: LogElement): void;
+    debug(message: any, context?: LogElement): void;
+    info(message: any, context?: LogElement): void;
+    warn(message: any, context?: LogElement): void;
+    error(message: any, context?: LogElement): void;
+    fatal(message: any, context?: LogElement): void;
+}
+declare class NoopLogger extends Logger {
+    constructor(category: string);
+    protected outputLogEntry(_entry: StructuredLog): void;
+}
+
+type EvaluationContextParams = {
+    [key: string]: any;
+};
+/**
+ * A component that contributes a specific field (or fields) to an evaluation context.
+ * Register components with {@link EvaluationContextProvider} at construction time.
+ */
+interface IEvaluationContextProvider<TCtxPart extends EvaluationContextPart = object, TCtxParam extends EvaluationContextParams = object> {
+    /**
+     * Called during `EvaluationContextProvider.getContext()`. Implementations should
+     * mutate `ctx` directly to add their contribution (e.g. `ctx.location = ...`).
+     */
+    getContext(params: Partial<TCtxParam>): Promise<Partial<TCtxPart>>;
+}
+
+/**
+ * Assembles a per-request evaluation context from a set of registered components.
+ *
+ * Usage:
+ * ```ts
+ * const provider = new EvaluationContextProvider().registerProviderComponent(locationService);
+ *
+ * const ctx = await provider.getContext({ ip: req.ip, customer: 'cust-123' });
+ * const enabled = await featureFlags.getBooleanValue('my-flag', false, ctx);
+ * ```
+ */
+declare class EvaluationContextProvider<TContext extends BaseEvaluationContext = BaseEvaluationContext, TParams extends BaseEvaluationContext = BaseEvaluationContext> implements IEvaluationContextProvider<TContext, TParams> {
+    private readonly logger;
+    private readonly components;
+    constructor(baseProvider: IEvaluationContextProvider<TContext, TParams>);
+    /**
+     * Resolves a full evaluation context for the given request parameters.
+     * Each registered component is given the opportunity to enrich the context.
+     * The `ip` field is consumed by components and is not included in the returned context.
+     * All other fields in `params` (e.g. `customer`) are included verbatim.
+     */
+    getContext(params?: Partial<TParams>): Promise<Partial<TContext>>;
+    registerProviderComponent<TCompCtxPart extends EvaluationContextPart, TCompCtxParam extends EvaluationContextParams>(component: IEvaluationContextProvider<TCompCtxPart, TCompCtxParam>): EvaluationContextProvider<Partial<TContext & TCompCtxPart>, Partial<TParams & TCompCtxParam>>;
+}
+
+interface IClosable {
+    close(): void;
+}
+
+type onUpdateHandler = () => void;
+interface FlagEvaluationReporter extends BaseHook, IClosable {
+    startExporter(): void;
+    stopExporter(): void;
+    updateFlagIdsByKeyMap(flagIdsByKey: Map<string, string>): void;
+}
+
+type FlagEvaluationReporterConfig = {};
+type EvaluationEvent = {
+    timestamp: Date;
+    flagId: string;
+    outcome: EvaluationDetails$1<FlagValue>;
+    context: EvaluationContext;
+};
+declare class FlagEvaluationPublisher implements FlagEvaluationReporter {
+    private readonly httpClient;
+    private readonly config;
+    private readonly logger;
+    private evaluationEvents;
+    private exporterJob?;
+    private ongoingHttpRequest?;
+    private flagIdsByKey;
+    constructor(httpClient: AxiosInstance, config?: FlagEvaluationReporterConfig);
+    after(hookContext: Readonly<HookContext>, evaluationDetails: EvaluationDetails$1<FlagValue>): void;
+    startExporter(): void;
+    stopExporter(): void;
+    updateFlagIdsByKeyMap(flagIdsByKey: Map<string, string>): void;
+    close(): void;
+    protected exportEvaluationEventsChunk(): Promise<EvaluationEvent[]>;
+    protected postMetrics(chunk: EvaluationEvent[]): Promise<void>;
+}
+
+type PrimitiveValue = null | boolean | string | number;
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+type JsonArray = JsonValue[];
+type JsonValue = PrimitiveValue | JsonObject | JsonArray;
+type ResolutionReason = keyof typeof StandardResolutionReasons | (string & Record<never, never>);
+type FlagMetadata = Record<string, string | number | boolean>;
+type ResolutionDetails<U> = {
+    value: U;
+    variant?: string;
+    flagMetadata?: FlagMetadata;
+    reason?: ResolutionReason;
+    errorCode?: ErrorCode;
+    errorMessage?: string;
+};
+type EvaluationDetails<T extends JsonValue> = {
+    flagKey: string;
+    flagMetadata: Readonly<FlagMetadata>;
+} & ResolutionDetails<T>;
+
+interface FeatureFlagsClientAPI {
+    getBooleanValue(flagKey: string, defaultValue: boolean, context?: EvaluationContext): Promise<boolean>;
+    getBooleanDetails(flagKey: string, defaultValue: boolean, context?: EvaluationContext): Promise<EvaluationDetails<boolean>>;
+    registerUpdateListener(handler: onUpdateHandler): void;
+}
+
+type FeatureFlagsClientConfig = {};
+
+type FeatureFlagsPollingProviderConfig = {
+    /**
+     * Whether the SDK should attempt to regularly poll the Atono service for feature flags definition updates. If this
+     * option is disabled, the SDK will still attempt to get an initial set of flag configurations from the Atono
+     * service, and will retry until it has successfully retrieved this initial set, but will not attempt to refresh
+     * them again.
+     *
+     * Default: true
+     */
+    autoSync?: boolean;
+    /**
+     * The frequency in milliseconds that the SDK should attempt to regularly poll the Atono service for feature flags
+     * definition updates. If `autoSync` is disabled, this option is ignored.
+     *
+     * Default: 5000
+     */
+    syncInterval?: number;
+};
+
+type FeatureFlagsConfig = FeatureFlagsClientConfig & FeatureFlagsPollingProviderConfig;
+
+type LocationContext = {
+    location: LocationContext$1;
+};
+type LocationParams = {
+    clientIp: string;
+};
+interface LocationService extends IEvaluationContextProvider<LocationContext, LocationParams> {
+    getContext(params: Partial<LocationParams>): Promise<Partial<LocationContext>>;
+}
+
+declare class NoopLocationService implements LocationService {
+    getLocation(_ip?: string): Promise<undefined>;
+    getContext: (_param: Partial<LocationParams>) => Promise<{}>;
+}
+
+interface UsageReporterAPI extends IClosable {
+    record(usageKey: string, context?: EvaluationContext): void;
+    startPublisher(): void;
+    stopPublisher(): void;
+}
+
+type UsageReporterConfig = {};
+
+type SdkConfig = {
+    /**
+     * Overrides the base URL to the Atono API. This may be used to point the SDK to a local replica of the Atono
+     * service for resilience.
+     *
+     * Default: 'https://api.atono.io'
+     */
+    apiBaseUrl?: string;
+    /**
+     * Configurations for the feature flags module.
+     */
+    featureFlags?: FeatureFlagsConfig & {
+        /**
+         * Whether the SDK should publish flag evaluation events back to Atono. This allows the Atono app to suggest
+         * flag slicing values that are based on actual evaluations.
+         *
+         * Default: true
+         */
+        publishEvaluations?: boolean;
+    };
+    /**
+     * Configurations for the HTTP client.
+     */
+    httpClient?: {
+        /**
+         * The number of milliseconds to wait before timing out HTTP requests.
+         *
+         * Default: 2000
+         */
+        timeout?: number;
+    };
+    /**
+     * Configuration for the location service used by the evaluation context provider.
+     * Provide a custom implementation class to replace the default IP-based location service.
+     */
+    location?: {
+        /**
+         * Change the implementation of the location service. The location service is used by the
+         * evaluation context provider to resolve the user's geographic location from an IP address.
+         *
+         * This SDK provides two implementations out of the box:
+         *
+         * - IpBasedLocationService (default): Calls the Atono API with the provided IP to determine location.
+         *
+         * - NoopLocationService: Disables location resolution. Location-based flag slices will be ignored.
+         */
+        implementation?: new (httpClient: AxiosInstance) => LocationService;
+    };
+    /**
+     * Configurations for the SDK logger.
+     */
+    log?: LoggerConfig;
+    /**
+     * Configure the usage module.
+     */
+    usage?: UsageReporterConfig;
+};
+declare class Atono {
+    static fromEnvironmentKey(environmentKey: string, config?: SdkConfig): Atono;
+    getFeatureFlags(): Promise<FeatureFlagsClientAPI>;
+    getOpenFeatureProvider(): Promise<Provider>;
+    getLocationService(): LocationService;
+    getDefaultEvaluationContextProvider(): EvaluationContextProvider<BaseEvaluationContext & LocationContext, BaseEvaluationContext & LocationParams>;
+    getUsageReporter(): UsageReporterAPI;
+    /**
+     * It is important to stop all SDK processes that rely on timers here. Otherwise, they remain
+     * in memory and pollute the heap of our client's code.
+     */
+    close(): void;
+}
+
+export { Atono, EvaluationContextProvider, FlagEvaluationPublisher, LogLevels, NoopLocationService, NoopLogger };
+export type { BaseEvaluationContext, EvaluationContext, EvaluationContextParams, EvaluationContextPart, EvaluationDetails, FeatureFlagsClientAPI, FeatureFlagsConfig, IEvaluationContextProvider, LocationContext, LoggerConfig, LoggerListener, SdkConfig, StructuredLog, UsageReporterAPI, UsageReporterConfig };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@atono-io/server-sdk",
+  "version": "1.4.0-rc.2",
+  "description": "",
+  "type": "module",
+  "exports": {
+    "types": "./dist/types.d.ts",
+    "import": "./dist/esm/index.js",
+    "require": "./dist/cjs/index.js",
+    "default": "./dist/cjs/index.js"
+  },
+  "types": "./dist/types.d.ts",
+  "scripts": {
+    "build": "rm -rf dist && npm run build:commonjs && npm run build:esm && npm run build:rollup-types",
+    "build:commonjs": "esbuild src/index.ts --bundle --sourcemap --target=es2022 --platform=node --format=cjs --outfile=./dist/cjs/index.js --analyze && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json",
+    "build:esm": "esbuild src/index.ts --bundle --sourcemap --target=es2022 --platform=node --format=esm --outfile=./dist/esm/index.js --analyze && echo '{\"type\": \"module\"}' > dist/esm/package.json",
+    "build:rollup-types": "rollup -c ../../rollup.config.js",
+    "package-publish": "npm run build && npm pack && npm publish --access public --tag ${NPM_RELEASE_TAG:-latest}"
+  },
+  "keywords": [],
+  "author": "Atono Inc.",
+  "license": "ISC",
+  "dependencies": {
+    "@openfeature/core": "^1.2.0",
+    "@openfeature/server-sdk": "1.14.0",
+    "@types/object-hash": "^3.0.6",
+    "axios": "^1.15.2",
+    "json-logic-js": "^2.0.2",
+    "object-hash": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/json-logic-js": "^2.0.7"
+  }
+}