@flipfeatureflag/core 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,124 @@
+type FlagValue = boolean | string | number | Record<string, unknown>;
+type SdkReason = "rule_match" | "fallthrough" | "default" | "disabled";
+interface SdkContext {
+    userId?: string;
+    attributes?: Record<string, unknown>;
+}
+interface SdkEvaluateRequest {
+    env?: string;
+    context: SdkContext;
+    flagKeys?: string[];
+}
+interface SdkFlagEvaluation {
+    value: FlagValue;
+    variationKey: string;
+    reason: SdkReason;
+}
+interface SdkEvaluateResponse {
+    flags: Record<string, SdkFlagEvaluation>;
+    evalId?: string;
+    updatedAt?: string;
+}
+interface SdkMetadataResponse {
+    items: Flag[];
+    updatedAt: string;
+}
+interface SdkMetricEvent {
+    flagKey: string;
+    variationKey: string;
+    reason: SdkReason | string;
+    ts: string;
+    context?: SdkContext;
+}
+interface SdkMetricsRequest {
+    env?: string;
+    events: SdkMetricEvent[];
+}
+interface Flag {
+    id: string;
+    projectId: string;
+    key: string;
+    name: string;
+    description?: string;
+    type: "boolean" | "string" | "number" | "json";
+    enabled: boolean;
+    defaultValue: FlagValue;
+    variations?: FlagVariation[];
+    targeting?: TargetingRules;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FlagVariation {
+    key: string;
+    value: FlagValue;
+    description?: string;
+    weight?: number;
+}
+interface TargetingRules {
+    rules?: TargetingRule[];
+    fallthrough?: FlagValue;
+}
+interface TargetingRule {
+    conditions: Condition[];
+    variationKey: string;
+    rollout?: number;
+}
+type ConditionOperator = "eq" | "ne" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains";
+interface Condition {
+    attribute: string;
+    operator: ConditionOperator;
+    value: string | number | boolean | string[];
+}
+interface FlipFlagClientOptions {
+    url: string;
+    sdkKey: string;
+    env?: string;
+    appName?: string;
+    refreshIntervalMs?: number;
+    metricsIntervalMs?: number;
+    disableRefresh?: boolean;
+    disableMetrics?: boolean;
+    context?: SdkContext;
+    fetch?: typeof fetch;
+}
+interface FlagsStatus {
+    ready: boolean;
+    error?: Error;
+    updatedAt?: string;
+}
+interface FlagEvaluationResult extends SdkFlagEvaluation {
+    flagKey: string;
+}
+type FlipFlagEvent = "ready" | "update" | "error" | "metrics";
+type FlipFlagListener = (payload?: unknown) => void;
+
+declare class FlipFlagClient {
+    private options;
+    private http;
+    private emitter;
+    private status;
+    private evaluations;
+    private refreshTimer?;
+    private metricsTimer?;
+    private metricsBuffer;
+    private context;
+    constructor(options: FlipFlagClientOptions);
+    start(): Promise<void>;
+    stop(): void;
+    on(event: FlipFlagEvent, listener: FlipFlagListener): void;
+    off(event: FlipFlagEvent, listener: FlipFlagListener): void;
+    getStatus(): FlagsStatus;
+    getContext(): SdkContext;
+    updateContext(partial: SdkContext): void;
+    getAllFlags(): Record<string, SdkFlagEvaluation>;
+    isEnabled(flagKey: string, defaultValue?: boolean): boolean;
+    getVariant(flagKey: string, defaultValue?: FlagValue): SdkFlagEvaluation;
+    private evaluate;
+    private recordEvaluation;
+    private refresh;
+    private applyEvaluate;
+    flushMetrics(): Promise<void>;
+    listFlagEvaluations(): FlagEvaluationResult[];
+}
+
+export { type Condition, type ConditionOperator, type Flag, type FlagEvaluationResult, type FlagValue, type FlagVariation, type FlagsStatus, FlipFlagClient, type FlipFlagClientOptions, type FlipFlagEvent, type FlipFlagListener, type SdkContext, type SdkEvaluateRequest, type SdkEvaluateResponse, type SdkFlagEvaluation, type SdkMetadataResponse, type SdkMetricEvent, type SdkMetricsRequest, type SdkReason, type TargetingRule, type TargetingRules };

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+type FlagValue = boolean | string | number | Record<string, unknown>;
+type SdkReason = "rule_match" | "fallthrough" | "default" | "disabled";
+interface SdkContext {
+    userId?: string;
+    attributes?: Record<string, unknown>;
+}
+interface SdkEvaluateRequest {
+    env?: string;
+    context: SdkContext;
+    flagKeys?: string[];
+}
+interface SdkFlagEvaluation {
+    value: FlagValue;
+    variationKey: string;
+    reason: SdkReason;
+}
+interface SdkEvaluateResponse {
+    flags: Record<string, SdkFlagEvaluation>;
+    evalId?: string;
+    updatedAt?: string;
+}
+interface SdkMetadataResponse {
+    items: Flag[];
+    updatedAt: string;
+}
+interface SdkMetricEvent {
+    flagKey: string;
+    variationKey: string;
+    reason: SdkReason | string;
+    ts: string;
+    context?: SdkContext;
+}
+interface SdkMetricsRequest {
+    env?: string;
+    events: SdkMetricEvent[];
+}
+interface Flag {
+    id: string;
+    projectId: string;
+    key: string;
+    name: string;
+    description?: string;
+    type: "boolean" | "string" | "number" | "json";
+    enabled: boolean;
+    defaultValue: FlagValue;
+    variations?: FlagVariation[];
+    targeting?: TargetingRules;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FlagVariation {
+    key: string;
+    value: FlagValue;
+    description?: string;
+    weight?: number;
+}
+interface TargetingRules {
+    rules?: TargetingRule[];
+    fallthrough?: FlagValue;
+}
+interface TargetingRule {
+    conditions: Condition[];
+    variationKey: string;
+    rollout?: number;
+}
+type ConditionOperator = "eq" | "ne" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains";
+interface Condition {
+    attribute: string;
+    operator: ConditionOperator;
+    value: string | number | boolean | string[];
+}
+interface FlipFlagClientOptions {
+    url: string;
+    sdkKey: string;
+    env?: string;
+    appName?: string;
+    refreshIntervalMs?: number;
+    metricsIntervalMs?: number;
+    disableRefresh?: boolean;
+    disableMetrics?: boolean;
+    context?: SdkContext;
+    fetch?: typeof fetch;
+}
+interface FlagsStatus {
+    ready: boolean;
+    error?: Error;
+    updatedAt?: string;
+}
+interface FlagEvaluationResult extends SdkFlagEvaluation {
+    flagKey: string;
+}
+type FlipFlagEvent = "ready" | "update" | "error" | "metrics";
+type FlipFlagListener = (payload?: unknown) => void;
+
+declare class FlipFlagClient {
+    private options;
+    private http;
+    private emitter;
+    private status;
+    private evaluations;
+    private refreshTimer?;
+    private metricsTimer?;
+    private metricsBuffer;
+    private context;
+    constructor(options: FlipFlagClientOptions);
+    start(): Promise<void>;
+    stop(): void;
+    on(event: FlipFlagEvent, listener: FlipFlagListener): void;
+    off(event: FlipFlagEvent, listener: FlipFlagListener): void;
+    getStatus(): FlagsStatus;
+    getContext(): SdkContext;
+    updateContext(partial: SdkContext): void;
+    getAllFlags(): Record<string, SdkFlagEvaluation>;
+    isEnabled(flagKey: string, defaultValue?: boolean): boolean;
+    getVariant(flagKey: string, defaultValue?: FlagValue): SdkFlagEvaluation;
+    private evaluate;
+    private recordEvaluation;
+    private refresh;
+    private applyEvaluate;
+    flushMetrics(): Promise<void>;
+    listFlagEvaluations(): FlagEvaluationResult[];
+}
+
+export { type Condition, type ConditionOperator, type Flag, type FlagEvaluationResult, type FlagValue, type FlagVariation, type FlagsStatus, FlipFlagClient, type FlipFlagClientOptions, type FlipFlagEvent, type FlipFlagListener, type SdkContext, type SdkEvaluateRequest, type SdkEvaluateResponse, type SdkFlagEvaluation, type SdkMetadataResponse, type SdkMetricEvent, type SdkMetricsRequest, type SdkReason, type TargetingRule, type TargetingRules };

package/dist/index.js

@@ -0,0 +1,289 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FlipFlagClient: () => FlipFlagClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/emitter.ts
+var Emitter = class {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  on(event, listener) {
+    const current = this.listeners.get(event) ?? /* @__PURE__ */ new Set();
+    current.add(listener);
+    this.listeners.set(event, current);
+  }
+  off(event, listener) {
+    const current = this.listeners.get(event);
+    if (!current) {
+      return;
+    }
+    current.delete(listener);
+  }
+  emit(event, payload) {
+    const current = this.listeners.get(event);
+    if (!current) {
+      return;
+    }
+    for (const listener of current) {
+      listener(payload);
+    }
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.sdkKey = options.sdkKey;
+    this.fetchFn = options.fetchFn;
+  }
+  async evaluate(request) {
+    return this.post("/v1/sdk/flags/evaluate", request);
+  }
+  async metrics(payload) {
+    await this.post("/v1/sdk/metrics", payload);
+  }
+  async get(path) {
+    const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+      method: "GET",
+      headers: this.headers()
+    });
+    return this.parseJson(response);
+  }
+  async post(path, payload) {
+    const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        ...this.headers(),
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(payload)
+    });
+    if (response.status === 202 && !response.headers.get("content-type")) {
+      return void 0;
+    }
+    return this.parseJson(response);
+  }
+  headers() {
+    return {
+      "x-sdk-key": this.sdkKey
+    };
+  }
+  async parseJson(response) {
+    if (!response.ok) {
+      const message = await response.text();
+      throw new Error(`flipFeatureFlag SDK request failed: ${response.status} ${message}`);
+    }
+    return await response.json();
+  }
+};
+
+// src/metrics.ts
+var MetricsBuffer = class {
+  constructor() {
+    this.events = [];
+  }
+  add(event) {
+    this.events.push(event);
+  }
+  drain() {
+    const drained = this.events;
+    this.events = [];
+    return drained;
+  }
+};
+function buildMetricEvent(flagKey, variationKey, reason, context) {
+  return {
+    flagKey,
+    variationKey,
+    reason,
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    context
+  };
+}
+function buildMetricsRequest(env, events) {
+  return {
+    env,
+    events
+  };
+}
+
+// src/client.ts
+var DEFAULT_REFRESH_MS = 15e3;
+var DEFAULT_METRICS_MS = 6e4;
+var FlipFlagClient = class {
+  constructor(options) {
+    this.emitter = new Emitter();
+    this.status = { ready: false };
+    this.evaluations = /* @__PURE__ */ new Map();
+    this.metricsBuffer = new MetricsBuffer();
+    if (!options.url) {
+      throw new Error("flipFeatureFlag SDK requires url");
+    }
+    if (!options.sdkKey) {
+      throw new Error("flipFeatureFlag SDK requires sdkKey");
+    }
+    this.options = {
+      refreshIntervalMs: DEFAULT_REFRESH_MS,
+      metricsIntervalMs: DEFAULT_METRICS_MS,
+      ...options
+    };
+    this.context = options.context ?? {};
+    const fetchFn = options.fetch ?? fetch;
+    this.http = new HttpClient({
+      baseUrl: this.options.url,
+      sdkKey: this.options.sdkKey,
+      fetchFn
+    });
+  }
+  async start() {
+    await this.refresh();
+    if (!this.options.disableRefresh) {
+      this.refreshTimer = setInterval(() => {
+        void this.refresh();
+      }, this.options.refreshIntervalMs);
+    }
+    if (!this.options.disableMetrics) {
+      this.metricsTimer = setInterval(() => {
+        void this.flushMetrics();
+      }, this.options.metricsIntervalMs);
+    }
+  }
+  stop() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = void 0;
+    }
+    if (this.metricsTimer) {
+      clearInterval(this.metricsTimer);
+      this.metricsTimer = void 0;
+    }
+  }
+  on(event, listener) {
+    this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  getStatus() {
+    return { ...this.status };
+  }
+  getContext() {
+    return { ...this.context };
+  }
+  updateContext(partial) {
+    this.context = {
+      ...this.context,
+      ...partial,
+      attributes: {
+        ...this.context.attributes ?? {},
+        ...partial.attributes ?? {}
+      }
+    };
+    void this.refresh();
+  }
+  getAllFlags() {
+    const result = {};
+    for (const [key, evaluation] of this.evaluations.entries()) {
+      result[key] = { ...evaluation };
+    }
+    return result;
+  }
+  isEnabled(flagKey, defaultValue = false) {
+    const evaluation = this.evaluate(flagKey, defaultValue);
+    return Boolean(evaluation.value);
+  }
+  getVariant(flagKey, defaultValue = false) {
+    return this.evaluate(flagKey, defaultValue);
+  }
+  evaluate(flagKey, defaultValue) {
+    const cached = this.evaluations.get(flagKey);
+    if (cached) {
+      return this.recordEvaluation(flagKey, cached);
+    }
+    void this.refresh([flagKey]);
+    return this.recordEvaluation(flagKey, {
+      value: defaultValue,
+      variationKey: "default",
+      reason: "default"
+    });
+  }
+  recordEvaluation(flagKey, evaluation) {
+    this.evaluations.set(flagKey, evaluation);
+    this.metricsBuffer.add(
+      buildMetricEvent(flagKey, evaluation.variationKey, evaluation.reason, this.context)
+    );
+    return evaluation;
+  }
+  async refresh(flagKeys) {
+    try {
+      const response = await this.http.evaluate({
+        env: this.options.env,
+        context: this.context,
+        flagKeys
+      });
+      this.applyEvaluate(response);
+      if (!this.status.ready) {
+        this.status.ready = true;
+        this.emitter.emit("ready");
+      }
+      this.emitter.emit("update");
+    } catch (error) {
+      this.status.error = error;
+      this.emitter.emit("error", error);
+    }
+  }
+  applyEvaluate(response) {
+    this.evaluations.clear();
+    for (const [key, evaluation] of Object.entries(response.flags)) {
+      this.evaluations.set(key, evaluation);
+    }
+    this.status.updatedAt = response.updatedAt;
+  }
+  async flushMetrics() {
+    const events = this.metricsBuffer.drain();
+    if (events.length === 0) {
+      return;
+    }
+    try {
+      await this.http.metrics(buildMetricsRequest(this.options.env, events));
+      this.emitter.emit("metrics", events);
+    } catch (error) {
+      this.status.error = error;
+      this.emitter.emit("error", error);
+    }
+  }
+  listFlagEvaluations() {
+    const result = [];
+    for (const [flagKey, evaluation] of this.evaluations.entries()) {
+      result.push({ flagKey, ...evaluation });
+    }
+    return result;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlipFlagClient
+});

package/dist/index.mjs

@@ -0,0 +1,262 @@
+// src/emitter.ts
+var Emitter = class {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  on(event, listener) {
+    const current = this.listeners.get(event) ?? /* @__PURE__ */ new Set();
+    current.add(listener);
+    this.listeners.set(event, current);
+  }
+  off(event, listener) {
+    const current = this.listeners.get(event);
+    if (!current) {
+      return;
+    }
+    current.delete(listener);
+  }
+  emit(event, payload) {
+    const current = this.listeners.get(event);
+    if (!current) {
+      return;
+    }
+    for (const listener of current) {
+      listener(payload);
+    }
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.sdkKey = options.sdkKey;
+    this.fetchFn = options.fetchFn;
+  }
+  async evaluate(request) {
+    return this.post("/v1/sdk/flags/evaluate", request);
+  }
+  async metrics(payload) {
+    await this.post("/v1/sdk/metrics", payload);
+  }
+  async get(path) {
+    const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+      method: "GET",
+      headers: this.headers()
+    });
+    return this.parseJson(response);
+  }
+  async post(path, payload) {
+    const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        ...this.headers(),
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(payload)
+    });
+    if (response.status === 202 && !response.headers.get("content-type")) {
+      return void 0;
+    }
+    return this.parseJson(response);
+  }
+  headers() {
+    return {
+      "x-sdk-key": this.sdkKey
+    };
+  }
+  async parseJson(response) {
+    if (!response.ok) {
+      const message = await response.text();
+      throw new Error(`flipFeatureFlag SDK request failed: ${response.status} ${message}`);
+    }
+    return await response.json();
+  }
+};
+
+// src/metrics.ts
+var MetricsBuffer = class {
+  constructor() {
+    this.events = [];
+  }
+  add(event) {
+    this.events.push(event);
+  }
+  drain() {
+    const drained = this.events;
+    this.events = [];
+    return drained;
+  }
+};
+function buildMetricEvent(flagKey, variationKey, reason, context) {
+  return {
+    flagKey,
+    variationKey,
+    reason,
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    context
+  };
+}
+function buildMetricsRequest(env, events) {
+  return {
+    env,
+    events
+  };
+}
+
+// src/client.ts
+var DEFAULT_REFRESH_MS = 15e3;
+var DEFAULT_METRICS_MS = 6e4;
+var FlipFlagClient = class {
+  constructor(options) {
+    this.emitter = new Emitter();
+    this.status = { ready: false };
+    this.evaluations = /* @__PURE__ */ new Map();
+    this.metricsBuffer = new MetricsBuffer();
+    if (!options.url) {
+      throw new Error("flipFeatureFlag SDK requires url");
+    }
+    if (!options.sdkKey) {
+      throw new Error("flipFeatureFlag SDK requires sdkKey");
+    }
+    this.options = {
+      refreshIntervalMs: DEFAULT_REFRESH_MS,
+      metricsIntervalMs: DEFAULT_METRICS_MS,
+      ...options
+    };
+    this.context = options.context ?? {};
+    const fetchFn = options.fetch ?? fetch;
+    this.http = new HttpClient({
+      baseUrl: this.options.url,
+      sdkKey: this.options.sdkKey,
+      fetchFn
+    });
+  }
+  async start() {
+    await this.refresh();
+    if (!this.options.disableRefresh) {
+      this.refreshTimer = setInterval(() => {
+        void this.refresh();
+      }, this.options.refreshIntervalMs);
+    }
+    if (!this.options.disableMetrics) {
+      this.metricsTimer = setInterval(() => {
+        void this.flushMetrics();
+      }, this.options.metricsIntervalMs);
+    }
+  }
+  stop() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = void 0;
+    }
+    if (this.metricsTimer) {
+      clearInterval(this.metricsTimer);
+      this.metricsTimer = void 0;
+    }
+  }
+  on(event, listener) {
+    this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  getStatus() {
+    return { ...this.status };
+  }
+  getContext() {
+    return { ...this.context };
+  }
+  updateContext(partial) {
+    this.context = {
+      ...this.context,
+      ...partial,
+      attributes: {
+        ...this.context.attributes ?? {},
+        ...partial.attributes ?? {}
+      }
+    };
+    void this.refresh();
+  }
+  getAllFlags() {
+    const result = {};
+    for (const [key, evaluation] of this.evaluations.entries()) {
+      result[key] = { ...evaluation };
+    }
+    return result;
+  }
+  isEnabled(flagKey, defaultValue = false) {
+    const evaluation = this.evaluate(flagKey, defaultValue);
+    return Boolean(evaluation.value);
+  }
+  getVariant(flagKey, defaultValue = false) {
+    return this.evaluate(flagKey, defaultValue);
+  }
+  evaluate(flagKey, defaultValue) {
+    const cached = this.evaluations.get(flagKey);
+    if (cached) {
+      return this.recordEvaluation(flagKey, cached);
+    }
+    void this.refresh([flagKey]);
+    return this.recordEvaluation(flagKey, {
+      value: defaultValue,
+      variationKey: "default",
+      reason: "default"
+    });
+  }
+  recordEvaluation(flagKey, evaluation) {
+    this.evaluations.set(flagKey, evaluation);
+    this.metricsBuffer.add(
+      buildMetricEvent(flagKey, evaluation.variationKey, evaluation.reason, this.context)
+    );
+    return evaluation;
+  }
+  async refresh(flagKeys) {
+    try {
+      const response = await this.http.evaluate({
+        env: this.options.env,
+        context: this.context,
+        flagKeys
+      });
+      this.applyEvaluate(response);
+      if (!this.status.ready) {
+        this.status.ready = true;
+        this.emitter.emit("ready");
+      }
+      this.emitter.emit("update");
+    } catch (error) {
+      this.status.error = error;
+      this.emitter.emit("error", error);
+    }
+  }
+  applyEvaluate(response) {
+    this.evaluations.clear();
+    for (const [key, evaluation] of Object.entries(response.flags)) {
+      this.evaluations.set(key, evaluation);
+    }
+    this.status.updatedAt = response.updatedAt;
+  }
+  async flushMetrics() {
+    const events = this.metricsBuffer.drain();
+    if (events.length === 0) {
+      return;
+    }
+    try {
+      await this.http.metrics(buildMetricsRequest(this.options.env, events));
+      this.emitter.emit("metrics", events);
+    } catch (error) {
+      this.status.error = error;
+      this.emitter.emit("error", error);
+    }
+  }
+  listFlagEvaluations() {
+    const result = [];
+    for (const [flagKey, evaluation] of this.evaluations.entries()) {
+      result.push({ flagKey, ...evaluation });
+    }
+    return result;
+  }
+};
+export {
+  FlipFlagClient
+};

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@flipfeatureflag/core",
+  "version": "0.1.1",
+  "description": "flipFeatureFlag core SDK",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run"
+  }
+}

package/src/client.ts

@@ -0,0 +1,198 @@
+import { Emitter } from "./emitter";
+import { HttpClient } from "./http";
+import { buildMetricEvent, buildMetricsRequest, MetricsBuffer } from "./metrics";
+import {
+  FlagEvaluationResult,
+  FlagValue,
+  FlagsStatus,
+  FlipFlagClientOptions,
+  FlipFlagEvent,
+  FlipFlagListener,
+  SdkEvaluateResponse,
+  SdkFlagEvaluation,
+  SdkContext,
+} from "./types";
+
+const DEFAULT_REFRESH_MS = 15000;
+const DEFAULT_METRICS_MS = 60000;
+
+export class FlipFlagClient {
+  private options: Required<Pick<FlipFlagClientOptions, "url" | "sdkKey">> & FlipFlagClientOptions;
+  private http: HttpClient;
+  private emitter = new Emitter();
+  private status: FlagsStatus = { ready: false };
+  private evaluations = new Map<string, SdkFlagEvaluation>();
+  private refreshTimer?: ReturnType<typeof setInterval>;
+  private metricsTimer?: ReturnType<typeof setInterval>;
+  private metricsBuffer = new MetricsBuffer();
+  private context: SdkContext;
+
+  constructor(options: FlipFlagClientOptions) {
+    if (!options.url) {
+      throw new Error("flipFeatureFlag SDK requires url");
+    }
+    if (!options.sdkKey) {
+      throw new Error("flipFeatureFlag SDK requires sdkKey");
+    }
+
+    this.options = {
+      refreshIntervalMs: DEFAULT_REFRESH_MS,
+      metricsIntervalMs: DEFAULT_METRICS_MS,
+      ...options,
+    } as Required<Pick<FlipFlagClientOptions, "url" | "sdkKey">> & FlipFlagClientOptions;
+
+    this.context = options.context ?? {};
+
+    const fetchFn = options.fetch ?? fetch;
+    this.http = new HttpClient({
+      baseUrl: this.options.url,
+      sdkKey: this.options.sdkKey,
+      fetchFn,
+    });
+  }
+
+  async start(): Promise<void> {
+    await this.refresh();
+
+    if (!this.options.disableRefresh) {
+      this.refreshTimer = setInterval(() => {
+        void this.refresh();
+      }, this.options.refreshIntervalMs);
+    }
+
+    if (!this.options.disableMetrics) {
+      this.metricsTimer = setInterval(() => {
+        void this.flushMetrics();
+      }, this.options.metricsIntervalMs);
+    }
+  }
+
+  stop() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = undefined;
+    }
+    if (this.metricsTimer) {
+      clearInterval(this.metricsTimer);
+      this.metricsTimer = undefined;
+    }
+  }
+
+  on(event: FlipFlagEvent, listener: FlipFlagListener) {
+    this.emitter.on(event, listener);
+  }
+
+  off(event: FlipFlagEvent, listener: FlipFlagListener) {
+    this.emitter.off(event, listener);
+  }
+
+  getStatus(): FlagsStatus {
+    return { ...this.status };
+  }
+
+  getContext(): SdkContext {
+    return { ...this.context };
+  }
+
+  updateContext(partial: SdkContext) {
+    this.context = {
+      ...this.context,
+      ...partial,
+      attributes: {
+        ...(this.context.attributes ?? {}),
+        ...(partial.attributes ?? {}),
+      },
+    };
+    void this.refresh();
+  }
+
+  getAllFlags(): Record<string, SdkFlagEvaluation> {
+    const result: Record<string, SdkFlagEvaluation> = {};
+    for (const [key, evaluation] of this.evaluations.entries()) {
+      result[key] = { ...evaluation };
+    }
+    return result;
+  }
+
+  isEnabled(flagKey: string, defaultValue: boolean = false): boolean {
+    const evaluation = this.evaluate(flagKey, defaultValue);
+    return Boolean(evaluation.value);
+  }
+
+  getVariant(flagKey: string, defaultValue: FlagValue = false): SdkFlagEvaluation {
+    return this.evaluate(flagKey, defaultValue);
+  }
+
+  private evaluate(flagKey: string, defaultValue: FlagValue): SdkFlagEvaluation {
+    const cached = this.evaluations.get(flagKey);
+    if (cached) {
+      return this.recordEvaluation(flagKey, cached);
+    }
+
+    void this.refresh([flagKey]);
+    return this.recordEvaluation(flagKey, {
+      value: defaultValue,
+      variationKey: "default",
+      reason: "default",
+    });
+  }
+
+  private recordEvaluation(flagKey: string, evaluation: SdkFlagEvaluation): SdkFlagEvaluation {
+    this.evaluations.set(flagKey, evaluation);
+    this.metricsBuffer.add(
+      buildMetricEvent(flagKey, evaluation.variationKey, evaluation.reason, this.context),
+    );
+    return evaluation;
+  }
+
+  private async refresh(flagKeys?: string[]) {
+    try {
+      const response = await this.http.evaluate({
+        env: this.options.env,
+        context: this.context,
+        flagKeys,
+      });
+      this.applyEvaluate(response);
+
+      if (!this.status.ready) {
+        this.status.ready = true;
+        this.emitter.emit("ready");
+      }
+
+      this.emitter.emit("update");
+    } catch (error) {
+      this.status.error = error as Error;
+      this.emitter.emit("error", error);
+    }
+  }
+
+  private applyEvaluate(response: SdkEvaluateResponse) {
+    this.evaluations.clear();
+    for (const [key, evaluation] of Object.entries(response.flags)) {
+      this.evaluations.set(key, evaluation);
+    }
+    this.status.updatedAt = response.updatedAt;
+  }
+
+  async flushMetrics(): Promise<void> {
+    const events = this.metricsBuffer.drain();
+    if (events.length === 0) {
+      return;
+    }
+    try {
+      await this.http.metrics(buildMetricsRequest(this.options.env, events));
+      this.emitter.emit("metrics", events);
+    } catch (error) {
+      this.status.error = error as Error;
+      this.emitter.emit("error", error);
+    }
+  }
+
+  listFlagEvaluations(): FlagEvaluationResult[] {
+    const result: FlagEvaluationResult[] = [];
+    for (const [flagKey, evaluation] of this.evaluations.entries()) {
+      result.push({ flagKey, ...evaluation });
+    }
+    return result;
+  }
+}

package/src/emitter.ts

@@ -0,0 +1,29 @@
+import { FlipFlagEvent, FlipFlagListener } from "./types";
+
+export class Emitter {
+  private listeners = new Map<FlipFlagEvent, Set<FlipFlagListener>>();
+
+  on(event: FlipFlagEvent, listener: FlipFlagListener) {
+    const current = this.listeners.get(event) ?? new Set();
+    current.add(listener);
+    this.listeners.set(event, current);
+  }
+
+  off(event: FlipFlagEvent, listener: FlipFlagListener) {
+    const current = this.listeners.get(event);
+    if (!current) {
+      return;
+    }
+    current.delete(listener);
+  }
+
+  emit(event: FlipFlagEvent, payload?: unknown) {
+    const current = this.listeners.get(event);
+    if (!current) {
+      return;
+    }
+    for (const listener of current) {
+      listener(payload);
+    }
+  }
+}

package/src/http.ts

@@ -0,0 +1,64 @@
+import { SdkEvaluateRequest, SdkEvaluateResponse, SdkMetricsRequest } from "./types";
+
+export interface HttpClientOptions {
+  baseUrl: string;
+  sdkKey: string;
+  fetchFn: typeof fetch;
+}
+
+export class HttpClient {
+  private baseUrl: string;
+  private sdkKey: string;
+  private fetchFn: typeof fetch;
+
+  constructor(options: HttpClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.sdkKey = options.sdkKey;
+    this.fetchFn = options.fetchFn;
+  }
+
+  async evaluate(request: SdkEvaluateRequest): Promise<SdkEvaluateResponse> {
+    return this.post("/v1/sdk/flags/evaluate", request);
+  }
+
+  async metrics(payload: SdkMetricsRequest): Promise<void> {
+    await this.post("/v1/sdk/metrics", payload);
+  }
+
+  private async get<T>(path: string): Promise<T> {
+    const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+      method: "GET",
+      headers: this.headers(),
+    });
+    return this.parseJson(response);
+  }
+
+  private async post<T>(path: string, payload: unknown): Promise<T> {
+    const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        ...this.headers(),
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(payload),
+    });
+    if (response.status === 202 && !response.headers.get("content-type")) {
+      return undefined as T;
+    }
+    return this.parseJson(response);
+  }
+
+  private headers() {
+    return {
+      "x-sdk-key": this.sdkKey,
+    };
+  }
+
+  private async parseJson<T>(response: Response): Promise<T> {
+    if (!response.ok) {
+      const message = await response.text();
+      throw new Error(`flipFeatureFlag SDK request failed: ${response.status} ${message}`);
+    }
+    return (await response.json()) as T;
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export { FlipFlagClient } from "./client";

package/src/metrics.ts

@@ -0,0 +1,37 @@
+import { SdkContext, SdkMetricEvent, SdkMetricsRequest } from "./types";
+
+export class MetricsBuffer {
+  private events: SdkMetricEvent[] = [];
+
+  add(event: SdkMetricEvent) {
+    this.events.push(event);
+  }
+
+  drain(): SdkMetricEvent[] {
+    const drained = this.events;
+    this.events = [];
+    return drained;
+  }
+}
+
+export function buildMetricEvent(
+  flagKey: string,
+  variationKey: string,
+  reason: string,
+  context?: SdkContext,
+): SdkMetricEvent {
+  return {
+    flagKey,
+    variationKey,
+    reason,
+    ts: new Date().toISOString(),
+    context,
+  };
+}
+
+export function buildMetricsRequest(env: string | undefined, events: SdkMetricEvent[]): SdkMetricsRequest {
+  return {
+    env,
+    events,
+  };
+}

package/src/types.ts

@@ -0,0 +1,121 @@
+export type FlagValue = boolean | string | number | Record<string, unknown>;
+
+export type SdkReason = "rule_match" | "fallthrough" | "default" | "disabled";
+
+export interface SdkContext {
+  userId?: string;
+  attributes?: Record<string, unknown>;
+}
+
+export interface SdkEvaluateRequest {
+  env?: string;
+  context: SdkContext;
+  flagKeys?: string[];
+}
+
+export interface SdkFlagEvaluation {
+  value: FlagValue;
+  variationKey: string;
+  reason: SdkReason;
+}
+
+export interface SdkEvaluateResponse {
+  flags: Record<string, SdkFlagEvaluation>;
+  evalId?: string;
+  updatedAt?: string;
+}
+
+export interface SdkMetadataResponse {
+  items: Flag[];
+  updatedAt: string;
+}
+
+export interface SdkMetricEvent {
+  flagKey: string;
+  variationKey: string;
+  reason: SdkReason | string;
+  ts: string;
+  context?: SdkContext;
+}
+
+export interface SdkMetricsRequest {
+  env?: string;
+  events: SdkMetricEvent[];
+}
+
+export interface Flag {
+  id: string;
+  projectId: string;
+  key: string;
+  name: string;
+  description?: string;
+  type: "boolean" | "string" | "number" | "json";
+  enabled: boolean;
+  defaultValue: FlagValue;
+  variations?: FlagVariation[];
+  targeting?: TargetingRules;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface FlagVariation {
+  key: string;
+  value: FlagValue;
+  description?: string;
+  weight?: number;
+}
+
+export interface TargetingRules {
+  rules?: TargetingRule[];
+  fallthrough?: FlagValue;
+}
+
+export interface TargetingRule {
+  conditions: Condition[];
+  variationKey: string;
+  rollout?: number;
+}
+
+export type ConditionOperator =
+  | "eq"
+  | "ne"
+  | "in"
+  | "not_in"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "contains";
+
+export interface Condition {
+  attribute: string;
+  operator: ConditionOperator;
+  value: string | number | boolean | string[];
+}
+
+export interface FlipFlagClientOptions {
+  url: string;
+  sdkKey: string;
+  env?: string;
+  appName?: string;
+  refreshIntervalMs?: number;
+  metricsIntervalMs?: number;
+  disableRefresh?: boolean;
+  disableMetrics?: boolean;
+  context?: SdkContext;
+  fetch?: typeof fetch;
+}
+
+export interface FlagsStatus {
+  ready: boolean;
+  error?: Error;
+  updatedAt?: string;
+}
+
+export interface FlagEvaluationResult extends SdkFlagEvaluation {
+  flagKey: string;
+}
+
+export type FlipFlagEvent = "ready" | "update" | "error" | "metrics";
+
+export type FlipFlagListener = (payload?: unknown) => void;

package/test/client.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from "vitest";
+import { FlipFlagClient } from "../src/client";
+
+function createResponse(payload: unknown) {
+  return {
+    ok: true,
+    status: 200,
+    headers: new Headers({ "content-type": "application/json" }),
+    json: async () => payload,
+    text: async () => JSON.stringify(payload),
+  } as Response;
+}
+
+describe("FlipFlagClient (remote)", () => {
+  it("fetches evaluations on start", async () => {
+    const fetchMock = vi.fn(async () =>
+      createResponse({
+        flags: {
+          new_checkout: {
+            value: true,
+            variationKey: "on",
+            reason: "rule_match",
+          },
+        },
+        updatedAt: "2026-02-03T12:00:00Z",
+      }),
+    );
+
+    const client = new FlipFlagClient({
+      url: "https://api.example.com",
+      sdkKey: "test",
+      disableRefresh: true,
+      disableMetrics: true,
+      fetch: fetchMock as unknown as typeof fetch,
+    });
+
+    await client.start();
+    expect(client.isEnabled("new_checkout")).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("flushes metrics", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(
+        createResponse({
+          flags: {
+            flag_a: { value: true, variationKey: "on", reason: "rule_match" },
+          },
+        }),
+      )
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 202,
+        headers: new Headers(),
+        json: async () => ({}),
+        text: async () => "",
+      } as Response);
+
+    const client = new FlipFlagClient({
+      url: "https://api.example.com",
+      sdkKey: "test",
+      disableRefresh: true,
+      disableMetrics: true,
+      fetch: fetchMock as unknown as typeof fetch,
+    });
+
+    await client.start();
+    client.isEnabled("flag_a");
+    await client.flushMetrics();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"]
+}