@omniretail/omniflags-core 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Thrown when the provider encounters a permanent, non-recoverable error
+ * (e.g. 404 — invalid SDK key). The client will stop polling on this error.
+ */
+export declare class PermanentProviderError extends Error {
+    constructor(message: string);
+}
+export type FlagType = "boolean" | "string" | "number" | "json";
+export type ClauseOp = "eq" | "neq" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | "gt" | "gte" | "lt" | "lte" | "exists" | "not_exists";
+export type EvaluationReason = "STATIC" | "DEFAULT" | "TARGETING_MATCH" | "SPLIT" | "ROLLOUT" | "PREREQUISITE_FAILED" | "ERROR" | "STALE";
+export type ErrorCode = "FLAG_NOT_FOUND" | "TYPE_MISMATCH" | "PROVIDER_NOT_READY" | "PROVIDER_FATAL" | "MISSING_TARGETING_KEY" | "INVALID_CONTEXT" | "PARSE_ERROR" | "STALE_CONFIG" | "UNKNOWN";
+export type ProviderEvent = "PROVIDER_READY" | "PROVIDER_ERROR" | "PROVIDER_CONFIGURATION_CHANGED" | "PROVIDER_STALE" | "PROVIDER_LOADING_STATE_CHANGED";
+export type FlagOrigin = "NONE" | "CACHE" | "SERVER";
+export type LoadingState = {
+    /** True while a network request is in flight. */
+    isFetching: boolean;
+    /** True until any flag data is available (cache or server). */
+    isLoading: boolean;
+    /** Where the current flags came from. */
+    origin: FlagOrigin;
+    /** Last fetch error, reset on the next successful fetch. */
+    error: Error | null;
+};
+export interface Clause {
+    attribute: string;
+    op: ClauseOp;
+    values: unknown[];
+    caseSensitive?: boolean;
+}
+export interface RolloutSplit {
+    variant: string;
+    weight: number;
+}
+export interface RuleSchedule {
+    start?: string;
+    end?: string;
+}
+export interface FlagRule {
+    ruleId: string;
+    clauses: Clause[];
+    rollout?: RolloutSplit[];
+    serve?: string;
+    schedule?: RuleSchedule;
+}
+/**
+ * Per-environment flag config as received from the distribution API.
+ * Matches evaluation-spec v2 §2.2.
+ */
+export interface FlagConfig {
+    key: string;
+    type: FlagType;
+    enabled: boolean;
+    defaultValue: string;
+    variations: Record<string, string>;
+    rules?: FlagRule[];
+    rolloutPercentage?: number;
+    salt?: string;
+    revision?: number;
+}
+export interface FlagSnapshot {
+    envKey: string;
+    revision: number;
+    generatedAt: string;
+    staleAt?: string;
+    /** Server-driven polling interval in ms. SDKs must use this value. */
+    pollingIntervalMs: number;
+    /** Server-driven metrics flush interval in ms. */
+    metricsFlushIntervalMs: number;
+    /** Server-driven max events per metrics flush payload. */
+    metricsMaxBatchSize: number;
+    flags: FlagConfig[];
+}
+export interface EvaluationContext {
+    agentId?: number;
+    customerId?: number;
+    country?: string;
+    lga?: string;
+    city?: string;
+    businessId?: number;
+    sourceId?: number;
+    businessBranchId?: number;
+    stockPointId?: string;
+    customerRef?: string;
+    walletId?: string;
+    omnipayId?: number;
+    terminalId?: string;
+    [key: string]: unknown;
+}
+export interface EvaluationResult<T = unknown> {
+    value: T;
+    variant: string | null;
+    reason: EvaluationReason;
+    ruleId: string | null;
+    errorCode: ErrorCode | null;
+}
+export interface Hook {
+    before?(flagKey: string, context: EvaluationContext): void;
+    after?(flagKey: string, result: EvaluationResult): void;
+    error?(flagKey: string, error: unknown): void;
+}
+export interface CacheAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+export type ProviderStatus = "not_ready" | "ready" | "error" | "stale";
+export interface FlagProvider {
+    readonly status: ProviderStatus;
+    /** Initialize and return the first snapshot. sdkKey is the only credential needed. */
+    initialize(sdkKey: string): Promise<FlagSnapshot>;
+    refresh?(sdkKey: string): Promise<FlagSnapshot | null>;
+    shutdown?(): Promise<void>;
+    onEvent?(handler: (event: ProviderEvent, detail?: unknown) => void): void;
+}
+export interface OmniFlagsOptions {
+    /** The SDK key issued for your application and environment. */
+    sdkKey: string;
+    /** Evaluation lifecycle hooks. */
+    hooks?: Hook[];
+    /**
+     * Custom provider — for testing or advanced use cases only.
+     * In production the SDK uses its built-in CDN-backed provider.
+     */
+    provider?: FlagProvider;
+}
+export interface MetricEvent {
+    flagKey: string;
+    variant: string;
+    count: number;
+    windowStart?: string;
+}
+export interface MetricsPayload {
+    envKey: string;
+    events: MetricEvent[];
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+// ── Errors ───────────────────────────────────────────────────────────────
+/**
+ * Thrown when the provider encounters a permanent, non-recoverable error
+ * (e.g. 404 — invalid SDK key). The client will stop polling on this error.
+ */
+export class PermanentProviderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PermanentProviderError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@omniretail/omniflags-core",
+  "version": "1.0.0",
+  "description": "OmniFlags feature flag SDK — core evaluator, cache, and transport",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["feature-flags", "omniflags"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}