@ops-ai/react-router-toggly 1.0.0

package/dist/server.js

@@ -0,0 +1,2294 @@
+import { normalizeEntityContext, registerContext, appendEvaluationContext } from '@ops-ai/toggly-hooks-types';
+import { fromHttpRequest, snapshotEvaluatedBooleans, parseDefinitionsPayload, evaluateDefinitions } from '@ops-ai/toggly-eval';
+export { fromHttpRequest } from '@ops-ai/toggly-eval';
+import { AsyncLocalStorage } from 'async_hooks';
+import { buildFlagGateIndex, applyLocalGate } from '@ops-ai/toggly-local-gates';
+import WebSocket from 'ws';
+import { readResponseBody, parseEvaluatedResponseBody } from '@ops-ai/toggly-signed-defs';
+import { createRequire } from 'module';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { redirect } from 'react-router';
+
+// src/core/index.ts
+
+// src/core/types.ts
+var TogglyError = class extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "TogglyError";
+  }
+};
+var TogglyNetworkError = class extends TogglyError {
+  constructor(message, cause) {
+    super(message, "NETWORK_ERROR", cause);
+    this.name = "TogglyNetworkError";
+  }
+};
+var TogglyConfigError = class extends TogglyError {
+  constructor(message) {
+    super(message, "CONFIG_ERROR");
+    this.name = "TogglyConfigError";
+  }
+};
+var TogglyTimeoutError = class extends TogglyError {
+  constructor(message) {
+    super(message, "TIMEOUT_ERROR");
+    this.name = "TogglyTimeoutError";
+  }
+};
+var DEFAULT_CONFIG = {
+  baseUrl: "https://definitions.toggly.io",
+  environment: "Production",
+  timeout: 1e4,
+  debug: false,
+  evaluationMode: "remote"
+};
+function mergeConfig(config) {
+  return {
+    ...DEFAULT_CONFIG,
+    ...config
+  };
+}
+function buildDefinitionsUrl(config, context) {
+  const { baseUrl, appKey, environment, groups, claims, evaluationMode } = mergeConfig(config);
+  if (!appKey) {
+    throw new Error("appKey is required");
+  }
+  const mode = evaluationMode ?? "remote";
+  const pathSegment = mode === "local" ? "definitions-signed" : "evaluated-signed";
+  const url = new URL(`${baseUrl}/${pathSegment}/${appKey}/${environment}`);
+  if (mode === "local") {
+    return url.toString();
+  }
+  const fromParam = context;
+  appendEvaluationContext(
+    url,
+    {
+      identity: fromParam?.identity,
+      groups: groups,
+      claims: claims
+    },
+    "evaluated"
+  );
+  return url.toString();
+}
+function isFeatureEnabledLocal(defsByKey, featureKey, evalCtx = {}, defaultValue = false) {
+  if (!defsByKey || defsByKey.size === 0) {
+    return defaultValue;
+  }
+  if (!defsByKey.has(featureKey)) {
+    return defaultValue;
+  }
+  return evaluateDefinitions(defsByKey, featureKey, evalCtx);
+}
+function createLogger(debug) {
+  return {
+    debug: (...args) => {
+      if (debug) {
+        console.debug("[Toggly]", ...args);
+      }
+    },
+    info: (...args) => {
+      if (debug) {
+        console.info("[Toggly]", ...args);
+      }
+    },
+    warn: (...args) => {
+      console.warn("[Toggly]", ...args);
+    },
+    error: (...args) => {
+      console.error("[Toggly]", ...args);
+    }
+  };
+}
+function parseIdentity(value) {
+  if (!value) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed === "string") {
+      return parsed;
+    }
+    if (typeof parsed === "object" && parsed !== null) {
+      return parsed.identity || parsed.id || parsed.userId || parsed.sub;
+    }
+  } catch {
+  }
+  return value;
+}
+async function fetchWithTimeout(url, options = {}, timeout = 1e4) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal
+    });
+    return response;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// src/core/constants.ts
+var STORAGE_KEYS = {
+  /** Identity cookie/storage key */
+  IDENTITY: "toggly_identity",
+  /** Feature flags cache key */
+  FLAGS: "toggly_flags",
+  /** Config cache key */
+  CONFIG: "toggly_config",
+  /** Last fetch timestamp key */
+  LAST_FETCH: "toggly_last_fetch"
+};
+var HEADERS = {
+  /** Identity header */
+  IDENTITY: "x-toggly-identity",
+  /** Feature flags header */
+  FLAGS: "x-toggly-flags",
+  /** Cache control */
+  CACHE_CONTROL: "cache-control"
+};
+var TOGGLY_LOADER_KEY = "__toggly";
+
+// src/core/telemetry/hash.ts
+var utf8Encoder = new TextEncoder();
+function hashIdentity(identity) {
+  let hash = 2166136261;
+  const bytes = utf8Encoder.encode(identity);
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 16777619);
+  }
+  const unsigned = hash >>> 0;
+  return unsigned > 2147483647 ? unsigned - 4294967296 : unsigned;
+}
+function toProtobufTimestamp(date = /* @__PURE__ */ new Date()) {
+  const ms = date.getTime();
+  const seconds = Math.floor(ms / 1e3);
+  const nanos = ms % 1e3 * 1e6;
+  return { seconds, nanos };
+}
+function protobufTimestampToIso(ts) {
+  return new Date(ts.seconds * 1e3 + Math.floor(ts.nanos / 1e6)).toISOString();
+}
+
+// src/core/telemetry/usage-batcher.ts
+var MAX_UNIQUE_USER_HASHES_PER_FEATURE = 1e4;
+var MAX_APPLICATION_UNIQUE_USER_HASHES = 1e4;
+var MAX_FEATURES_PER_BATCH = 500;
+function emptyVariant() {
+  return { checkCount: 0, requestCount: 0, usedCount: 0, viewedCount: 0 };
+}
+function emptyFeature() {
+  return {
+    variantStats: /* @__PURE__ */ new Map(),
+    uniqueUsersEnabled: /* @__PURE__ */ new Set(),
+    uniqueUsersDisabled: /* @__PURE__ */ new Set(),
+    uniqueUsersUsed: /* @__PURE__ */ new Set(),
+    uniqueUsersViewed: /* @__PURE__ */ new Set(),
+    uniqueUserHashes: /* @__PURE__ */ new Set(),
+    uniqueViewedUserHashes: /* @__PURE__ */ new Set()
+  };
+}
+var UsageBatcher = class {
+  constructor(options) {
+    this.perFeature = /* @__PURE__ */ new Map();
+    this.appUnique = /* @__PURE__ */ new Set();
+    this.droppedFeatures = false;
+    this.definitionCacheHits = 0;
+    this.definitionCacheMisses = 0;
+    this.appKey = options.appKey;
+    this.environment = options.environment;
+    this.instanceName = options.instanceName;
+    this.appVersion = options.appVersion;
+    this.processStartTime = options.processStartTime ?? /* @__PURE__ */ new Date();
+    this.maxUniqueHashesPerFeature = options.maxUniqueHashesPerFeature ?? MAX_UNIQUE_USER_HASHES_PER_FEATURE;
+    this.maxApplicationUniqueHashes = options.maxApplicationUniqueHashes ?? MAX_APPLICATION_UNIQUE_USER_HASHES;
+    this.maxFeatures = options.maxFeatures ?? MAX_FEATURES_PER_BATCH;
+  }
+  /** Count a definition-refresh outcome served from local/cache (not a new revision). */
+  recordDefinitionCacheHit() {
+    this.definitionCacheHits += 1;
+  }
+  /** Count a definition-refresh that applied a new revision from the network. */
+  recordDefinitionCacheMiss() {
+    this.definitionCacheMisses += 1;
+  }
+  get(feature) {
+    let agg = this.perFeature.get(feature);
+    if (!agg) {
+      if (this.perFeature.size >= this.maxFeatures) {
+        this.droppedFeatures = true;
+        return null;
+      }
+      agg = emptyFeature();
+      this.perFeature.set(feature, agg);
+    }
+    return agg;
+  }
+  getVariant(agg, variant) {
+    let stats = agg.variantStats.get(variant);
+    if (!stats) {
+      stats = emptyVariant();
+      agg.variantStats.set(variant, stats);
+    }
+    return stats;
+  }
+  addHashCapped(set, hash, max) {
+    if (set.has(hash) || set.size < max) {
+      set.add(hash);
+    }
+  }
+  trackAppUnique(hash) {
+    this.addHashCapped(this.appUnique, hash, this.maxApplicationUniqueHashes);
+  }
+  /**
+   * Record a feature evaluation.
+   *
+   * `checkCount` increments on every call. `requestCount` maps to .NET
+   * UniqueRequestEnabled/Disabled when `uniqueRequest` is true.
+   */
+  recordCheck(feature, enabled, identity, variant, uniqueRequest = false) {
+    const agg = this.get(feature);
+    if (!agg) return;
+    const name = variant ?? (enabled ? "enabled" : "disabled");
+    const stats = this.getVariant(agg, name);
+    stats.checkCount += 1;
+    if (uniqueRequest) {
+      stats.requestCount += 1;
+    }
+    if (identity) {
+      const hash = hashIdentity(identity);
+      this.trackAppUnique(hash);
+      if (enabled) {
+        this.addHashCapped(agg.uniqueUsersEnabled, hash, this.maxUniqueHashesPerFeature);
+      } else {
+        this.addHashCapped(agg.uniqueUsersDisabled, hash, this.maxUniqueHashesPerFeature);
+      }
+    }
+  }
+  recordUsage(feature, identity, variant = "enabled") {
+    const agg = this.get(feature);
+    if (!agg) return;
+    this.getVariant(agg, variant).usedCount += 1;
+    if (identity) {
+      const hash = hashIdentity(identity);
+      this.trackAppUnique(hash);
+      this.addHashCapped(agg.uniqueUsersUsed, hash, this.maxUniqueHashesPerFeature);
+      this.addHashCapped(agg.uniqueUserHashes, hash, this.maxUniqueHashesPerFeature);
+    }
+  }
+  recordView(feature, identity, variant = "enabled") {
+    const agg = this.get(feature);
+    if (!agg) return;
+    this.getVariant(agg, variant).viewedCount += 1;
+    if (identity) {
+      const hash = hashIdentity(identity);
+      this.trackAppUnique(hash);
+      this.addHashCapped(agg.uniqueUsersViewed, hash, this.maxUniqueHashesPerFeature);
+      this.addHashCapped(agg.uniqueViewedUserHashes, hash, this.maxUniqueHashesPerFeature);
+    }
+  }
+  isEmpty() {
+    return this.perFeature.size === 0 && this.appUnique.size === 0 && this.definitionCacheHits === 0 && this.definitionCacheMisses === 0;
+  }
+  hitFeatureCap() {
+    return this.droppedFeatures;
+  }
+  featureCount() {
+    return this.perFeature.size;
+  }
+  buildAndReset() {
+    if (this.isEmpty()) {
+      return null;
+    }
+    const payload = {
+      appKey: this.appKey,
+      environment: this.environment,
+      time: toProtobufTimestamp(),
+      stats: [],
+      totalUniqueUsers: this.appUnique.size,
+      uniqueUserHashes: [...this.appUnique],
+      processStartTime: toProtobufTimestamp(this.processStartTime)
+    };
+    if (this.instanceName) {
+      payload.instanceName = this.instanceName;
+    }
+    if (this.appVersion) {
+      payload.appVersion = this.appVersion;
+    }
+    if (this.definitionCacheHits > 0) {
+      payload.definitionCacheHits = this.definitionCacheHits;
+    }
+    if (this.definitionCacheMisses > 0) {
+      payload.definitionCacheMisses = this.definitionCacheMisses;
+    }
+    const uniqueUsersEnabled = {};
+    const uniqueUsersDisabled = {};
+    const uniqueUsersUsed = {};
+    for (const [feature, agg] of this.perFeature) {
+      const variantStats = {};
+      for (const [name, stats] of agg.variantStats) {
+        if (stats.checkCount > 0 || stats.requestCount > 0 || stats.usedCount > 0 || stats.viewedCount > 0) {
+          variantStats[name] = { ...stats };
+        }
+      }
+      if (agg.uniqueUsersEnabled.size > 0) {
+        uniqueUsersEnabled[feature] = [...agg.uniqueUsersEnabled];
+      }
+      if (agg.uniqueUsersDisabled.size > 0) {
+        uniqueUsersDisabled[feature] = [...agg.uniqueUsersDisabled];
+      }
+      if (agg.uniqueUsersUsed.size > 0) {
+        uniqueUsersUsed[feature] = [...agg.uniqueUsersUsed];
+      }
+      payload.stats.push({
+        feature,
+        uniqueContextIdentifierEnabledCount: agg.uniqueUsersEnabled.size,
+        uniqueContextIdentifierDisabledCount: agg.uniqueUsersDisabled.size,
+        uniqueUsersUsedCount: agg.uniqueUsersUsed.size,
+        uniqueUserHashes: [...agg.uniqueUserHashes],
+        uniqueViewedUserHashes: [...agg.uniqueViewedUserHashes],
+        variantStats
+      });
+    }
+    this.perFeature = /* @__PURE__ */ new Map();
+    this.appUnique = /* @__PURE__ */ new Set();
+    this.droppedFeatures = false;
+    this.definitionCacheHits = 0;
+    this.definitionCacheMisses = 0;
+    return {
+      payload,
+      uniqueUsersEnabled,
+      uniqueUsersDisabled,
+      uniqueUsersUsed
+    };
+  }
+  restoreFromBundle(bundle) {
+    const { payload } = bundle;
+    this.definitionCacheHits += payload.definitionCacheHits ?? 0;
+    this.definitionCacheMisses += payload.definitionCacheMisses ?? 0;
+    for (const hash of payload.uniqueUserHashes ?? []) {
+      this.trackAppUnique(hash);
+    }
+    for (const stat of payload.stats ?? []) {
+      const feature = stat.feature;
+      if (!feature) continue;
+      const agg = this.get(feature);
+      if (!agg) continue;
+      for (const [name, vs] of Object.entries(stat.variantStats ?? {})) {
+        const target = this.getVariant(agg, name);
+        target.checkCount += vs.checkCount ?? 0;
+        target.requestCount += vs.requestCount ?? 0;
+        target.usedCount += vs.usedCount ?? 0;
+        target.viewedCount += vs.viewedCount ?? 0;
+      }
+      for (const hash of stat.uniqueUserHashes ?? []) {
+        this.addHashCapped(agg.uniqueUserHashes, hash, this.maxUniqueHashesPerFeature);
+      }
+      for (const hash of stat.uniqueViewedUserHashes ?? []) {
+        this.addHashCapped(agg.uniqueViewedUserHashes, hash, this.maxUniqueHashesPerFeature);
+        this.addHashCapped(agg.uniqueUsersViewed, hash, this.maxUniqueHashesPerFeature);
+      }
+    }
+    this.mergeUniqueHashMap(bundle.uniqueUsersEnabled, "uniqueUsersEnabled");
+    this.mergeUniqueHashMap(bundle.uniqueUsersDisabled, "uniqueUsersDisabled");
+    this.mergeUniqueHashMap(bundle.uniqueUsersUsed, "uniqueUsersUsed");
+  }
+  mergeUniqueHashMap(snapshot2, field) {
+    for (const [feature, hashes] of Object.entries(snapshot2 ?? {})) {
+      const agg = this.get(feature);
+      if (!agg) continue;
+      for (const hash of hashes) {
+        this.addHashCapped(agg[field], hash, this.maxUniqueHashesPerFeature);
+        this.trackAppUnique(hash);
+      }
+    }
+  }
+};
+
+// src/core/telemetry/metrics-batcher.ts
+var MAX_METRIC_KEYS_PER_BATCH = 500;
+var MAX_OBSERVATIONS_PER_BATCH = 1e3;
+var MetricsBatcher = class {
+  constructor(options) {
+    this.measures = /* @__PURE__ */ new Map();
+    this.counters = /* @__PURE__ */ new Map();
+    this.observations = [];
+    this.droppedKeys = false;
+    this.appKey = options.appKey;
+    this.environment = options.environment;
+    this.instanceName = options.instanceName;
+    this.maxMetricKeys = options.maxMetricKeys ?? MAX_METRIC_KEYS_PER_BATCH;
+    this.maxObservations = options.maxObservations ?? MAX_OBSERVATIONS_PER_BATCH;
+  }
+  key(metric, feature) {
+    return `${metric}\0${feature ?? ""}`;
+  }
+  parseKey(key) {
+    const sep = key.indexOf("\0");
+    if (sep < 0) {
+      return { metric: key };
+    }
+    const metric = key.slice(0, sep);
+    const feature = key.slice(sep + 1);
+    return feature ? { metric, feature } : { metric };
+  }
+  addToMap(store, metric, value, options) {
+    const variant = options?.variant ?? "enabled";
+    const mapKey = this.key(metric, options?.feature);
+    let variants = store.get(mapKey);
+    if (!variants) {
+      if (store.size >= this.maxMetricKeys) {
+        this.droppedKeys = true;
+        return;
+      }
+      variants = /* @__PURE__ */ new Map();
+      store.set(mapKey, variants);
+    }
+    variants.set(variant, (variants.get(variant) ?? 0) + value);
+  }
+  measure(metric, value, options) {
+    this.addToMap(this.measures, metric, value, options);
+  }
+  incrementCounter(metric, value = 1, options) {
+    this.addToMap(this.counters, metric, value, options);
+  }
+  observe(metric, value, options) {
+    if (this.observations.length >= this.maxObservations) {
+      this.droppedKeys = true;
+      return;
+    }
+    this.observations.push({
+      time: /* @__PURE__ */ new Date(),
+      metric,
+      feature: options?.feature,
+      variant: options?.variant ?? "enabled",
+      value
+    });
+  }
+  isEmpty() {
+    return this.measures.size === 0 && this.counters.size === 0 && this.observations.length === 0;
+  }
+  hitCap() {
+    return this.droppedKeys;
+  }
+  drainMap(store) {
+    const out = [];
+    for (const [key, variants] of store) {
+      const parsed = this.parseKey(key);
+      const variantValues = {};
+      for (const [variant, value] of variants) {
+        if (value !== 0) {
+          variantValues[variant] = value;
+        }
+      }
+      if (Object.keys(variantValues).length > 0) {
+        out.push({
+          metric: parsed.metric,
+          ...parsed.feature ? { feature: parsed.feature } : {},
+          variantValues
+        });
+      }
+    }
+    store.clear();
+    return out;
+  }
+  buildAndReset() {
+    if (this.isEmpty()) {
+      return null;
+    }
+    const observationGroups = /* @__PURE__ */ new Map();
+    for (const obs of this.observations) {
+      const groupKey = `${obs.time.toISOString()}\0${obs.metric}\0${obs.feature ?? ""}`;
+      let group = observationGroups.get(groupKey);
+      if (!group) {
+        group = {
+          time: toProtobufTimestamp(obs.time),
+          metric: obs.metric,
+          ...obs.feature ? { feature: obs.feature } : {},
+          variantValues: {}
+        };
+        observationGroups.set(groupKey, group);
+      }
+      group.variantValues[obs.variant] = obs.value;
+    }
+    this.observations = [];
+    this.droppedKeys = false;
+    const payload = {
+      appKey: this.appKey,
+      environment: this.environment,
+      time: toProtobufTimestamp(),
+      stats: this.drainMap(this.measures),
+      counters: this.drainMap(this.counters),
+      observations: [...observationGroups.values()]
+    };
+    if (this.instanceName) {
+      payload.instanceName = this.instanceName;
+    }
+    return payload;
+  }
+  restoreFromPayload(payload) {
+    for (const stat of payload.stats ?? []) {
+      for (const [variant, value] of Object.entries(stat.variantValues ?? {})) {
+        this.measure(stat.metric, value, { feature: stat.feature, variant });
+      }
+    }
+    for (const counter of payload.counters ?? []) {
+      for (const [variant, value] of Object.entries(counter.variantValues ?? {})) {
+        this.incrementCounter(counter.metric, value, {
+          feature: counter.feature,
+          variant
+        });
+      }
+    }
+    for (const obs of payload.observations ?? []) {
+      for (const [variant, value] of Object.entries(obs.variantValues ?? {})) {
+        this.observe(obs.metric, value, { feature: obs.feature, variant });
+      }
+    }
+  }
+};
+
+// src/core/sdk-identity.ts
+var SDK_ID = "react-router";
+var SDK_VERSION = "1.0.0";
+function sdkUserAgent() {
+  return `toggly-${SDK_ID}/${SDK_VERSION}`;
+}
+
+// src/core/telemetry/https-client.ts
+var DEFAULT_METRICS_BASE_URL = "https://app.toggly.io/";
+var DEFAULT_TELEMETRY_FLUSH_MS = 6e4;
+function ensureTrailingSlash(baseUrl) {
+  return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}
+function usagePayloadToHttpJson(payload) {
+  return {
+    ...payload,
+    time: protobufTimestampToIso(payload.time),
+    ...payload.processStartTime ? { processStartTime: protobufTimestampToIso(payload.processStartTime) } : {}
+  };
+}
+function metricsPayloadToHttpJson(payload) {
+  return {
+    ...payload,
+    time: protobufTimestampToIso(payload.time),
+    observations: (payload.observations ?? []).map((obs) => ({
+      ...obs,
+      time: protobufTimestampToIso(obs.time)
+    }))
+  };
+}
+var HttpsTelemetryClient = class {
+  constructor(options = {}) {
+    this.baseUrl = ensureTrailingSlash(options.metricsBaseUrl ?? DEFAULT_METRICS_BASE_URL);
+    this.userAgent = options.userAgent ?? sdkUserAgent();
+    this.fetchImpl = options.fetchImpl ?? fetch.bind(globalThis);
+  }
+  getUserAgent() {
+    return this.userAgent;
+  }
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+  /**
+   * POST JSON. Returns true on 2xx, false on soft-fail (network / non-2xx).
+   */
+  async post(path2, body) {
+    try {
+      const url = new URL(path2.replace(/^\//, ""), this.baseUrl).toString();
+      const response = await this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          "User-Agent": this.userAgent
+        },
+        body: JSON.stringify(body)
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  sendUsageStats(payload) {
+    return this.post("api/usage/stats", usagePayloadToHttpJson(payload));
+  }
+  sendMetrics(payload) {
+    return this.post("api/metrics", metricsPayloadToHttpJson(payload));
+  }
+};
+function resolveMetricsBaseUrl(raw) {
+  const trimmed = (raw ?? "").trim();
+  if (!trimmed) {
+    return DEFAULT_METRICS_BASE_URL;
+  }
+  return ensureTrailingSlash(trimmed);
+}
+function isTelemetryEnvDisabled() {
+  try {
+    return typeof process !== "undefined" && process.env?.TOGGLY_DISABLE_TELEMETRY === "1";
+  } catch {
+    return false;
+  }
+}
+function resolveTelemetryEnableFlag(explicit, defaultWhenUnset) {
+  if (isTelemetryEnvDisabled()) {
+    return false;
+  }
+  return explicit ?? defaultWhenUnset;
+}
+
+// src/core/telemetry/index.ts
+var _TelemetryRuntime = class _TelemetryRuntime {
+  constructor(config, logger) {
+    this.usageBatcher = null;
+    this.metricsBatcher = null;
+    this.usageClient = null;
+    this.metricsClient = null;
+    this.httpsClient = null;
+    this.usageTimer = null;
+    this.metricsTimer = null;
+    /** Single-flight drain promise (CF Worker TelemetryRuntime pattern). */
+    this.flushInFlight = null;
+    /** Set when flush/close is requested during an in-flight drain. */
+    this.pendingDrain = false;
+    this.closed = false;
+    this.processStartTime = /* @__PURE__ */ new Date();
+    this.signalHandlers = [];
+    const hasAppKey = Boolean(config.appKey);
+    this.transport = config.transport ?? "grpc";
+    this.attachProcessHandlers = config.attachProcessHandlers ?? this.transport === "grpc";
+    this.restoreOnSendFailure = config.restoreOnSendFailure ?? this.transport === "https";
+    this.config = {
+      appKey: config.appKey,
+      environment: config.environment,
+      metricsBaseUrl: resolveMetricsBaseUrl(config.metricsBaseUrl ?? DEFAULT_METRICS_BASE_URL),
+      // TOGGLY_DISABLE_TELEMETRY=1 wins over explicit true.
+      enableUsageTracking: resolveTelemetryEnableFlag(
+        config.enableUsageTracking,
+        hasAppKey
+      ),
+      enableMetrics: resolveTelemetryEnableFlag(config.enableMetrics, hasAppKey),
+      usageFlushInterval: config.usageFlushInterval ?? DEFAULT_TELEMETRY_FLUSH_MS,
+      metricsFlushInterval: config.metricsFlushInterval ?? DEFAULT_TELEMETRY_FLUSH_MS,
+      instanceName: config.instanceName,
+      appVersion: config.appVersion,
+      usageClient: config.usageClient,
+      metricsClient: config.metricsClient,
+      fetchImpl: config.fetchImpl
+    };
+    this.logger = logger ?? {
+      debug: () => {
+      },
+      warn: (...args) => console.warn("[Toggly]", ...args),
+      error: (...args) => console.error("[Toggly]", ...args)
+    };
+  }
+  get usageEnabled() {
+    return this.config.enableUsageTracking && !this.closed;
+  }
+  get metricsEnabled() {
+    return this.config.enableMetrics && !this.closed;
+  }
+  start() {
+    if (this.closed) return;
+    if (!this.config.enableUsageTracking && !this.config.enableMetrics) {
+      return;
+    }
+    if (this.config.usageClient !== void 0 || this.config.metricsClient !== void 0) {
+      this.usageClient = this.config.usageClient ?? null;
+      this.metricsClient = this.config.metricsClient ?? null;
+    } else if (this.transport === "https") {
+      this.httpsClient = new HttpsTelemetryClient({
+        metricsBaseUrl: this.config.metricsBaseUrl,
+        fetchImpl: this.config.fetchImpl
+      });
+      this.usageClient = {
+        sendStats: async (request) => {
+          const ok = await this.httpsClient.sendUsageStats(
+            request
+          );
+          return { ok };
+        }
+      };
+      this.metricsClient = {
+        sendMetrics: async (request) => {
+          const ok = await this.httpsClient.sendMetrics(
+            request
+          );
+          return { ok };
+        }
+      };
+    } else {
+      this.logger.warn(
+        "Usage/metrics enabled with gRPC transport but no clients were injected. Pass usageClient/metricsClient from createGrpcClients (optional @grpc/grpc-js)."
+      );
+    }
+    if (this.config.enableUsageTracking) {
+      this.usageBatcher = new UsageBatcher({
+        appKey: this.config.appKey,
+        environment: this.config.environment,
+        instanceName: this.config.instanceName,
+        appVersion: this.config.appVersion,
+        processStartTime: this.processStartTime
+      });
+      if (this.config.usageFlushInterval > 0) {
+        this.usageTimer = setInterval(() => {
+          void this.flush();
+        }, this.config.usageFlushInterval);
+        this.usageTimer.unref?.();
+      }
+    }
+    if (this.config.enableMetrics) {
+      this.metricsBatcher = new MetricsBatcher({
+        appKey: this.config.appKey,
+        environment: this.config.environment,
+        instanceName: this.config.instanceName
+      });
+      if (this.config.metricsFlushInterval > 0) {
+        this.metricsTimer = setInterval(() => {
+          void this.flush();
+        }, this.config.metricsFlushInterval);
+        this.metricsTimer.unref?.();
+      }
+    }
+    if (this.attachProcessHandlers) {
+      this.attachHandlers();
+    }
+  }
+  /* istanbul ignore next -- process signal exit paths; covered by attach/detach tests */
+  attachHandlers() {
+    if (typeof process === "undefined" || typeof process.on !== "function") {
+      return;
+    }
+    const flush = () => {
+      void this.flushAll();
+    };
+    process.on("beforeExit", flush);
+    this.signalHandlers.push({ event: "beforeExit", handler: flush });
+    for (const signal of ["SIGTERM", "SIGINT"]) {
+      try {
+        const onSignal = () => {
+          void this.handleProcessSignal(signal);
+        };
+        process.on(signal, onSignal);
+        this.signalHandlers.push({ event: signal, handler: onSignal });
+      } catch {
+      }
+    }
+  }
+  /* istanbul ignore next -- process.kill / process.exit on SIGTERM/SIGINT */
+  async handleProcessSignal(signal) {
+    try {
+      await Promise.race([
+        this.close(),
+        new Promise((resolve) => {
+          const timer = setTimeout(resolve, _TelemetryRuntime.SIGNAL_FLUSH_TIMEOUT_MS);
+          timer.unref?.();
+        })
+      ]);
+    } catch {
+    } finally {
+      this.detachProcessHandlers();
+      this.reemitSignalAndExit(signal);
+    }
+  }
+  /* istanbul ignore next -- process.kill / process.exit on SIGTERM/SIGINT */
+  reemitSignalAndExit(signal) {
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      const code = signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 0;
+      process.exit(code);
+    }
+  }
+  detachProcessHandlers() {
+    if (typeof process === "undefined" || typeof process.off !== "function") {
+      return;
+    }
+    for (const { event, handler } of this.signalHandlers) {
+      process.off(event, handler);
+    }
+    this.signalHandlers.length = 0;
+  }
+  recordCheck(feature, enabled, identity, variant, uniqueRequest = false) {
+    this.usageBatcher?.recordCheck(feature, enabled, identity, variant, uniqueRequest);
+  }
+  recordUsage(feature, identity, variant) {
+    this.usageBatcher?.recordUsage(feature, identity, variant);
+  }
+  recordView(feature, identity, variant) {
+    this.usageBatcher?.recordView(feature, identity, variant);
+  }
+  recordDefinitionCacheHit() {
+    this.usageBatcher?.recordDefinitionCacheHit();
+  }
+  recordDefinitionCacheMiss() {
+    this.usageBatcher?.recordDefinitionCacheMiss();
+  }
+  measure(metric, value, options) {
+    this.metricsBatcher?.measure(metric, value, options);
+  }
+  incrementCounter(metric, value = 1, options) {
+    this.metricsBatcher?.incrementCounter(metric, value, options);
+  }
+  observe(metric, value, options) {
+    this.metricsBatcher?.observe(metric, value, options);
+  }
+  shouldFlushForCaps() {
+    return Boolean(this.usageBatcher?.hitFeatureCap() || this.metricsBatcher?.hitCap());
+  }
+  /**
+   * Single-flight flush with pending-drain follow-up (CF Worker parity).
+   * Concurrent flush/close during an active send coalesces onto one drain and
+   * runs another pass so batches recorded mid-send are not stranded.
+   */
+  async flush() {
+    this.pendingDrain = true;
+    if (this.flushInFlight) {
+      return this.flushInFlight;
+    }
+    this.flushInFlight = this.drainUntilIdle();
+    return this.flushInFlight;
+  }
+  async flushAll() {
+    await this.flush();
+  }
+  /** @deprecated Prefer {@link flush}; kept for callers that split usage/metrics. */
+  async flushUsage() {
+    await this.flush();
+  }
+  /** @deprecated Prefer {@link flush}; kept for callers that split usage/metrics. */
+  async flushMetrics() {
+    await this.flush();
+  }
+  async drainUntilIdle() {
+    try {
+      while (this.pendingDrain) {
+        this.pendingDrain = false;
+        await this.flushInternal();
+      }
+    } finally {
+      this.flushInFlight = null;
+      if (this.pendingDrain) {
+        await this.flush();
+      }
+    }
+  }
+  async flushInternal() {
+    await Promise.all([this.sendUsageOnce(), this.sendMetricsOnce()]);
+  }
+  async sendUsageOnce() {
+    if (!this.usageBatcher) return;
+    const client = this.usageClient;
+    if (!client?.sendStats) {
+      this.logger.debug("Usage flush skipped: no usage client");
+      return;
+    }
+    const bundle = this.usageBatcher.buildAndReset();
+    if (!bundle) return;
+    try {
+      const result = await client.sendStats(bundle.payload);
+      if (this.restoreOnSendFailure && result && typeof result === "object" && "ok" in result && result.ok === false) {
+        this.usageBatcher.restoreFromBundle(bundle);
+        this.logger.debug("Usage HTTPS soft-fail; batch restored");
+      }
+    } catch (error) {
+      if (this.restoreOnSendFailure) {
+        this.usageBatcher.restoreFromBundle(bundle);
+      }
+      this.logger.error("Failed to send usage stats:", error);
+    }
+  }
+  async sendMetricsOnce() {
+    if (!this.metricsBatcher) return;
+    const client = this.metricsClient;
+    if (!client?.sendMetrics) {
+      this.logger.debug("Metrics flush skipped: no metrics client");
+      return;
+    }
+    const payload = this.metricsBatcher.buildAndReset();
+    if (!payload) return;
+    try {
+      const result = await client.sendMetrics(payload);
+      if (this.restoreOnSendFailure && result && typeof result === "object" && "ok" in result && result.ok === false) {
+        this.metricsBatcher.restoreFromPayload(payload);
+        this.logger.debug("Metrics HTTPS soft-fail; batch restored");
+      }
+    } catch (error) {
+      if (this.restoreOnSendFailure) {
+        this.metricsBatcher.restoreFromPayload(payload);
+      }
+      this.logger.error("Failed to send metrics:", error);
+    }
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.usageTimer) {
+      clearInterval(this.usageTimer);
+      this.usageTimer = null;
+    }
+    if (this.metricsTimer) {
+      clearInterval(this.metricsTimer);
+      this.metricsTimer = null;
+    }
+    this.detachProcessHandlers();
+    try {
+      await this.flush();
+    } finally {
+      try {
+        this.usageClient?.close?.();
+      } catch {
+      }
+      try {
+        this.metricsClient?.close?.();
+      } catch {
+      }
+      this.usageClient = null;
+      this.metricsClient = null;
+      this.httpsClient = null;
+      this.usageBatcher = null;
+      this.metricsBatcher = null;
+    }
+  }
+};
+/** Best-effort flush budget before re-emitting the signal so Node can exit. */
+_TelemetryRuntime.SIGNAL_FLUSH_TIMEOUT_MS = 2e3;
+var TelemetryRuntime = _TelemetryRuntime;
+var ambientStore = new AsyncLocalStorage();
+function snapshot(ctx) {
+  return {
+    ...ctx.identity !== void 0 ? { identity: ctx.identity } : {},
+    ...ctx.groups !== void 0 ? { groups: ctx.groups } : {},
+    ...ctx.claims !== void 0 ? { claims: ctx.claims } : {},
+    ...ctx.traits !== void 0 ? { traits: ctx.traits } : {},
+    ...ctx.request !== void 0 ? { request: ctx.request } : {}
+  };
+}
+function getAmbientEvalOverrides() {
+  const store = ambientStore.getStore();
+  return store ? snapshot(store) : void 0;
+}
+function runWithEvalContext(ctx, fn) {
+  return ambientStore.run(snapshot(ctx), fn);
+}
+function mergeIdentityContext(ambient, perCall) {
+  if (ambient == null && perCall == null) {
+    return void 0;
+  }
+  if (ambient == null) {
+    return perCall ? snapshot(perCall) : void 0;
+  }
+  if (perCall == null) {
+    return snapshot(ambient);
+  }
+  return {
+    identity: perCall.identity ?? ambient.identity,
+    groups: perCall.groups ?? ambient.groups,
+    claims: perCall.claims ?? ambient.claims,
+    traits: perCall.traits ?? ambient.traits,
+    request: perCall.request ?? ambient.request
+  };
+}
+
+// src/server/extract-context.ts
+function headersToBag(headers) {
+  const bag = {};
+  headers.forEach((value, key) => {
+    bag[key] = value;
+  });
+  return bag;
+}
+function getIdentityFromRequest(request, customCookieParser) {
+  const headerIdentity = request.headers.get(HEADERS.IDENTITY);
+  if (headerIdentity) {
+    return parseIdentity(headerIdentity);
+  }
+  const cookies = request.headers.get("cookie");
+  if (customCookieParser) {
+    return customCookieParser(cookies);
+  }
+  if (cookies) {
+    const identity = parseCookie(cookies, STORAGE_KEYS.IDENTITY);
+    if (identity) {
+      return parseIdentity(identity);
+    }
+  }
+  return void 0;
+}
+function parseCookie(cookies, name) {
+  const pairs = cookies.split(";");
+  for (const pair of pairs) {
+    const [key, value] = pair.trim().split("=");
+    if (key === name && value) {
+      try {
+        return decodeURIComponent(value);
+      } catch {
+        return value;
+      }
+    }
+  }
+  return void 0;
+}
+async function extractEvalContext(request, providers = {}) {
+  const headers = headersToBag(request.headers);
+  const headerRequest = fromHttpRequest(headers).request;
+  if (providers.getContext) {
+    const custom = await providers.getContext(request);
+    return {
+      identity: custom.identity,
+      groups: custom.groups,
+      // Prefer claims for UserClaims; ignore traits-as-claims from custom
+      claims: custom.claims,
+      traits: custom.traits,
+      request: {
+        ...headerRequest,
+        ...custom.request
+      }
+    };
+  }
+  let identity;
+  if (providers.getIdentity) {
+    identity = await providers.getIdentity(request);
+  } else {
+    identity = getIdentityFromRequest(
+      request,
+      providers.getIdentityFromCookies
+    );
+  }
+  const groups = providers.getGroups ? await providers.getGroups(request) : void 0;
+  const claims = providers.getClaims ? await providers.getClaims(request) : void 0;
+  const fromReq = fromHttpRequest(headers, { identity, groups, claims });
+  return {
+    identity: fromReq.identity,
+    groups: fromReq.groups,
+    claims: fromReq.claims,
+    request: fromReq.request
+  };
+}
+
+// src/server/sdk-identity.ts
+var SDK_ID2 = "react-router";
+var SDK_VERSION2 = "1.0.0";
+var SDK_HEADER_ID = "X-Toggly-Sdk";
+var SDK_HEADER_VERSION = "X-Toggly-Sdk-Version";
+function sdkUserAgent2() {
+  return `toggly-${SDK_ID2}/${SDK_VERSION2}`;
+}
+function sdkCustomHeaders() {
+  return {
+    [SDK_HEADER_ID]: SDK_ID2,
+    [SDK_HEADER_VERSION]: SDK_VERSION2
+  };
+}
+function appendSdkQueryParams(params) {
+  params.set("sdk", SDK_ID2);
+  params.set("sdkVersion", SDK_VERSION2);
+}
+function usesSdkCustomHeaders() {
+  const g = globalThis;
+  if (g.window !== void 0 && g.document !== void 0) {
+    return true;
+  }
+  if (g.navigator?.product === "ReactNative") {
+    return true;
+  }
+  return false;
+}
+function buildDefinitionFetchHeaders(existing = {}) {
+  const headers = { ...existing };
+  if (usesSdkCustomHeaders()) {
+    Object.assign(headers, sdkCustomHeaders());
+  } else {
+    headers["User-Agent"] = sdkUserAgent2();
+  }
+  return headers;
+}
+
+// src/server/ws-sync.ts
+var DEFINITIONS_REVISION_HEADER = "X-Definitions-Revision";
+var WS_RECONNECT_BASE_MS = 5e3;
+var WS_RECONNECT_MAX_MS = 6e4;
+var REFRESH_DEBOUNCE_MS = 300;
+function buildWebSocketUrl(baseUri, appKey, cachedEtag) {
+  const wsBase = baseUri.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://").replace(/\/$/, "");
+  const params = new URLSearchParams();
+  if (cachedEtag) {
+    params.set("rev", cachedEtag);
+  }
+  appendSdkQueryParams(params);
+  const query = params.toString();
+  return `${wsBase}/${appKey}/ws${query ? `?${query}` : ""}`;
+}
+function getNextReconnectDelayMs(attempt) {
+  return Math.min(WS_RECONNECT_BASE_MS * Math.pow(2, attempt), WS_RECONNECT_MAX_MS);
+}
+function shouldFetchOnSync(message, cachedEtag) {
+  if (message.type !== "sync") {
+    return false;
+  }
+  if (message.unchanged === true) {
+    return false;
+  }
+  if (!cachedEtag) {
+    return true;
+  }
+  if (message.etag && message.etag !== cachedEtag) {
+    return true;
+  }
+  return false;
+}
+function shouldFetchOnFlagsUpdated(message, cachedEtag) {
+  if (message.type !== "flags-updated" && message.type !== "update") {
+    return false;
+  }
+  if (!message.etag || !cachedEtag) {
+    return true;
+  }
+  return message.etag !== cachedEtag;
+}
+function shouldFetchOnSigningKeyUpdated(message) {
+  return message.type === "signing-key-updated";
+}
+function planFlagsUpdatedRefresh(message, previousRevision) {
+  if (shouldFetchOnSigningKeyUpdated(message)) {
+    return { action: "refresh-jwks" };
+  }
+  if (shouldFetchOnFlagsUpdated(message, previousRevision)) {
+    return { action: "refresh-pinned", pin: message.etag ?? null };
+  }
+  return { action: "none" };
+}
+function applyFlagsUpdatedPlan(plan, message, hooks) {
+  if (plan.action === "refresh-jwks") {
+    hooks.refreshJwks();
+    return;
+  }
+  if (plan.action === "refresh-pinned") {
+    hooks.refreshPinned(plan.pin);
+    return;
+  }
+  if (message.etag) {
+    hooks.cacheEtagIfPresent(message.etag);
+  }
+}
+function extractDefinitionsRevision(response) {
+  if (!response.headers?.get) {
+    return null;
+  }
+  return response.headers.get(DEFINITIONS_REVISION_HEADER) ?? response.headers.get("ETag");
+}
+function appendDefinitionsRevisionParam(url, rev) {
+  if (!rev) {
+    return url;
+  }
+  try {
+    const parsed = new URL(url);
+    parsed.searchParams.set("rev", rev);
+    return parsed.toString();
+  } catch {
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}rev=${encodeURIComponent(rev)}`;
+  }
+}
+var thisModuleUrl = import.meta.url;
+var nodeRequire = createRequire(thisModuleUrl);
+function resolveProtoRoot(moduleUrl = thisModuleUrl) {
+  const moduleDir = path.dirname(fileURLToPath(moduleUrl));
+  const candidates = [
+    // Built dist/cjs|esm/telemetry/grpc.js → packageRoot/proto
+    path.resolve(moduleDir, "..", "..", "..", "proto"),
+    // Built dist/telemetry/grpc.js → packageRoot/proto
+    path.resolve(moduleDir, "..", "..", "proto"),
+    // Built dist/index.js sibling layouts
+    path.resolve(moduleDir, "..", "proto"),
+    // Source src/telemetry/*.ts → packageRoot/proto
+    path.resolve(moduleDir, "..", "..", "proto"),
+    path.resolve(moduleDir, "proto")
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, "usage.proto"))) {
+      return candidate;
+    }
+  }
+  return candidates[0] ?? path.resolve(moduleDir, "..", "..", "proto");
+}
+var protoRoot = resolveProtoRoot();
+function grpcTarget(baseUrl) {
+  try {
+    const u = new URL(baseUrl.includes("://") ? baseUrl : `https://${baseUrl}`);
+    let host = u.host;
+    if (!host.includes(":")) {
+      host = `${host}:443`;
+    }
+    return host;
+  } catch {
+    const trimmed = baseUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
+    return trimmed.includes(":") ? trimmed : `${trimmed}:443`;
+  }
+}
+function resolveUserAgent(override) {
+  return sdkUserAgent();
+}
+function tryLoadGrpcModules() {
+  try {
+    const grpc = nodeRequire("@grpc/grpc-js");
+    const protoLoader = nodeRequire("@grpc/proto-loader");
+    return { grpc, protoLoader };
+  } catch {
+    return null;
+  }
+}
+function loadPackageDefinition(protoLoader, grpc, protoFile) {
+  const packageDefinition = protoLoader.loadSync(path.join(protoRoot, protoFile), {
+    keepCase: true,
+    longs: Number,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+    includeDirs: [protoRoot]
+  });
+  return grpc.loadPackageDefinition(packageDefinition);
+}
+function createMetadata(grpc, map) {
+  const metadata = new grpc.Metadata();
+  if (map) {
+    for (const [key, value] of Object.entries(map)) {
+      metadata.set(key, value);
+    }
+  }
+  return metadata;
+}
+function createGrpcClients(metricsBaseUrl = DEFAULT_METRICS_BASE_URL, userAgent) {
+  const modules = tryLoadGrpcModules();
+  if (!modules) {
+    return null;
+  }
+  const { grpc, protoLoader } = modules;
+  const target = grpcTarget(metricsBaseUrl);
+  const credentials = grpc.credentials.createSsl();
+  const ua = resolveUserAgent();
+  const defaultMeta = { UA: ua };
+  const usageDef = loadPackageDefinition(protoLoader, grpc, "usage.proto");
+  const metricsDef = loadPackageDefinition(protoLoader, grpc, "metrics.proto");
+  const UsageService = usageDef.Usage.Usage;
+  const MetricsService = metricsDef.Metrics.Metrics;
+  const usageStub = new UsageService(target, credentials);
+  const metricsStub = new MetricsService(target, credentials);
+  return {
+    usage: {
+      sendStats(request, metadata) {
+        return new Promise((resolve, reject) => {
+          usageStub.SendStats(
+            request,
+            createMetadata(grpc, { ...defaultMeta, ...metadata }),
+            (err, res) => {
+              if (err) reject(err);
+              else resolve(res ?? {});
+            }
+          );
+        });
+      },
+      close() {
+        usageStub.close();
+      }
+    },
+    metrics: {
+      sendMetrics(request, metadata) {
+        return new Promise((resolve, reject) => {
+          metricsStub.SendMetrics(
+            request,
+            createMetadata(grpc, { ...defaultMeta, ...metadata }),
+            (err, res) => {
+              if (err) reject(err);
+              else resolve(res ?? {});
+            }
+          );
+        });
+      },
+      close() {
+        metricsStub.close();
+      }
+    }
+  };
+}
+function isGrpcAvailable() {
+  return tryLoadGrpcModules() !== null;
+}
+
+// src/server/client.ts
+function resolveServerTelemetryFlags(config) {
+  const hasAppKey = Boolean(config.appKey);
+  return {
+    enableUsageTracking: resolveTelemetryEnableFlag(
+      config.enableUsageTracking,
+      hasAppKey
+    ),
+    enableMetrics: resolveTelemetryEnableFlag(config.enableMetrics, hasAppKey)
+  };
+}
+function resolveGrpcClients(config) {
+  if (config.usageClient !== void 0 || config.metricsClient !== void 0) {
+    return {
+      usageClient: config.usageClient,
+      metricsClient: config.metricsClient
+    };
+  }
+  const flags = resolveServerTelemetryFlags(config);
+  if (!flags.enableUsageTracking && !flags.enableMetrics) {
+    return {};
+  }
+  const transport = config.telemetryTransport ?? "grpc";
+  if (transport !== "grpc") {
+    return {};
+  }
+  if (!isGrpcAvailable()) {
+    console.warn(
+      "[Toggly] Usage/metrics enabled but @grpc/grpc-js and @grpc/proto-loader are not installed. Install them to send telemetry: npm install @grpc/grpc-js @grpc/proto-loader"
+    );
+    return { usageClient: null, metricsClient: null };
+  }
+  const clients = createGrpcClients(config.metricsBaseUrl);
+  if (!clients) {
+    console.warn("[Toggly] Failed to create gRPC clients; telemetry transport disabled");
+    return { usageClient: null, metricsClient: null };
+  }
+  return { usageClient: clients.usage, metricsClient: clients.metrics };
+}
+var TogglyServerClient = class {
+  constructor(config) {
+    /** Compatibility snapshot of locally evaluated booleans (hydration / afterRefresh). */
+    this.flags = {};
+    /** Raw definitions-signed models keyed by featureKey. */
+    this.definitions = /* @__PURE__ */ new Map();
+    this.hooks = [];
+    this.initialized = false;
+    /** Dedupes concurrent cold-start definition fetches. */
+    this.definitionsLoadPromise = null;
+    /** Single-flight for definition GET so concurrent joiners are not double-counted. */
+    this.definitionsFetchInFlight = null;
+    // WebSocket live updates
+    this.ws = null;
+    this.wsConnected = false;
+    this.wsReconnectTimer = null;
+    this.wsReconnectAttempt = 0;
+    this.refreshDebounceTimer = null;
+    this.cachedDefinitionsRevision = null;
+    this.pendingDefinitionsPin = null;
+    this.refreshTimer = null;
+    this.localGates = [];
+    this.localGateIndex = /* @__PURE__ */ new Map();
+    this.localGatesListeners = /* @__PURE__ */ new Set();
+    this.telemetry = null;
+    const telemetryFlags = resolveServerTelemetryFlags(config);
+    const grpcClients = resolveGrpcClients({ ...config, ...telemetryFlags });
+    this.config = mergeConfig({
+      ...config,
+      ...telemetryFlags,
+      ...grpcClients,
+      evaluationMode: "local",
+      telemetryTransport: config.telemetryTransport ?? "grpc",
+      telemetryAttachProcessHandlers: config.telemetryAttachProcessHandlers ?? (config.telemetryTransport ?? "grpc") === "grpc"
+    });
+    this.logger = createLogger(this.config.debug ?? false);
+    if (this.config.localGates) {
+      this.setLocalGates(this.config.localGates);
+    }
+    if (!this.config.appKey && !this.config.featureDefaults) {
+      this.logger.warn(
+        "No appKey provided and no featureDefaults set. All features will be disabled."
+      );
+    }
+    this.startTelemetry();
+  }
+  startTelemetry() {
+    if (!this.config.appKey || isTelemetryEnvDisabled()) {
+      return;
+    }
+    if (!this.config.enableUsageTracking && !this.config.enableMetrics) {
+      return;
+    }
+    if (this.telemetry) {
+      void this.telemetry.close();
+      this.telemetry = null;
+    }
+    this.telemetry = new TelemetryRuntime({
+      appKey: this.config.appKey,
+      environment: this.config.environment ?? "Production",
+      metricsBaseUrl: this.config.metricsBaseUrl,
+      enableUsageTracking: this.config.enableUsageTracking,
+      enableMetrics: this.config.enableMetrics,
+      usageFlushInterval: this.config.usageFlushInterval,
+      metricsFlushInterval: this.config.metricsFlushInterval,
+      instanceName: this.config.instanceName,
+      appVersion: this.config.appVersion,
+      transport: this.config.telemetryTransport ?? "grpc",
+      attachProcessHandlers: this.config.telemetryAttachProcessHandlers,
+      usageClient: this.config.usageClient,
+      metricsClient: this.config.metricsClient,
+      fetchImpl: this.config.telemetryFetch
+    });
+    this.telemetry.start();
+  }
+  recordCheckForKey(featureKey, enabled, identityOverride) {
+    if (!this.telemetry?.usageEnabled) {
+      return;
+    }
+    const identity = identityOverride?.identity ?? this.identity;
+    this.telemetry.recordCheck(featureKey, enabled, identity);
+  }
+  /** Soft-fail wrapper — definition refresh must not throw from telemetry. */
+  noteDefinitionCacheHit() {
+    try {
+      this.telemetry?.recordDefinitionCacheHit();
+    } catch {
+    }
+  }
+  noteDefinitionCacheMiss() {
+    try {
+      this.telemetry?.recordDefinitionCacheMiss();
+    } catch {
+    }
+  }
+  normalizeDefinitionsRevision(revision) {
+    if (!revision) {
+      return null;
+    }
+    return revision.replace(/^"+|"+$/g, "");
+  }
+  definitionsRevisionsMatch(previous, incoming) {
+    const a = this.normalizeDefinitionsRevision(previous);
+    const b = this.normalizeDefinitionsRevision(incoming);
+    if (!a || !b) {
+      return false;
+    }
+    return a === b;
+  }
+  /**
+   * Add a hook to the client
+   */
+  addHook(hook) {
+    const metadata = hook.getMetadata();
+    const exists = this.hooks.find((h) => h.getMetadata().name === metadata.name);
+    if (exists) {
+      this.logger.warn(`Hook "${metadata.name}" already registered. Skipping.`);
+      return;
+    }
+    this.hooks.push(hook);
+    this.logger.debug(`Hook "${metadata.name}" registered.`);
+  }
+  /**
+   * Remove a hook by name
+   */
+  removeHook(name) {
+    const index = this.hooks.findIndex((h) => h.getMetadata().name === name);
+    if (index > -1) {
+      this.hooks.splice(index, 1);
+      this.logger.debug(`Hook "${name}" removed.`);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Register device-local post-filter gates
+   */
+  setLocalGates(gates) {
+    this.localGates = [...gates];
+    this.localGateIndex = buildFlagGateIndex(this.localGates);
+  }
+  /**
+   * Notify subscribers that local gate state changed (no network)
+   */
+  notifyLocalGatesChanged() {
+    this.localGatesListeners.forEach((listener) => {
+      try {
+        listener();
+      } catch (error) {
+        this.logger.error("Local gate listener error:", error);
+      }
+    });
+  }
+  /**
+   * Subscribe to local gate changes
+   */
+  subscribeLocalGatesChanged(listener) {
+    this.localGatesListeners.add(listener);
+    return () => {
+      this.localGatesListeners.delete(listener);
+    };
+  }
+  buildEvalContext(identityOverride, entityContext) {
+    const merged = mergeIdentityContext(
+      getAmbientEvalOverrides(),
+      identityOverride
+    );
+    if (merged) {
+      const claims2 = merged.claims ?? this.config.claims;
+      return {
+        identity: merged.identity,
+        groups: merged.groups ?? this.config.groups,
+        traits: merged.traits ?? this.config.claims,
+        claims: claims2,
+        request: merged.request,
+        entity: entityContext ?? null
+      };
+    }
+    const claims = this.config.claims;
+    return {
+      identity: this.identity,
+      groups: this.config.groups,
+      traits: this.config.claims,
+      claims,
+      entity: entityContext ?? null
+    };
+  }
+  /**
+   * Evaluate a boolean snapshot for a specific identity without relying on
+   * shared mutable `this.flags` / `this.identity` (safe under concurrency).
+   */
+  snapshotFlags(identityOverride) {
+    return {
+      ...this.config.featureDefaults ?? {},
+      ...snapshotEvaluatedBooleans(
+        this.definitions,
+        this.buildEvalContext(identityOverride)
+      )
+    };
+  }
+  getEffectiveFlag(featureKey, defaultValue = false, entityContext, identityOverride) {
+    const evaluated = isFeatureEnabledLocal(
+      this.definitions,
+      featureKey,
+      this.buildEvalContext(identityOverride, entityContext),
+      this.config.featureDefaults?.[featureKey] ?? defaultValue
+    );
+    return applyLocalGate(evaluated, featureKey, this.localGates, this.localGateIndex);
+  }
+  getDefinitionsRevision() {
+    return this.cachedDefinitionsRevision;
+  }
+  cacheDefinitionsRevision(revision) {
+    const normalized = this.normalizeDefinitionsRevision(revision);
+    if (!normalized) {
+      return;
+    }
+    this.cachedDefinitionsRevision = normalized;
+  }
+  scheduleDebouncedRefresh(forceRevisionReset = false) {
+    if (this.refreshDebounceTimer) {
+      clearTimeout(this.refreshDebounceTimer);
+    }
+    this.refreshDebounceTimer = setTimeout(() => {
+      this.refreshDebounceTimer = null;
+      if (forceRevisionReset) {
+        this.cachedDefinitionsRevision = null;
+      }
+      void this.fetchFlags(this.identity);
+    }, REFRESH_DEBOUNCE_MS);
+  }
+  handleWsSyncMessage(message) {
+    const previousRevision = this.getDefinitionsRevision();
+    if (shouldFetchOnSync(message, previousRevision)) {
+      this.scheduleDebouncedRefresh();
+      return;
+    }
+    this.cacheDefinitionsRevision(message.etag);
+  }
+  handleWsUpdateMessage(message) {
+    applyFlagsUpdatedPlan(
+      planFlagsUpdatedRefresh(message, this.getDefinitionsRevision()),
+      message,
+      {
+        refreshJwks: () => this.scheduleDebouncedRefresh(true),
+        refreshPinned: (pin) => {
+          this.pendingDefinitionsPin = pin;
+          this.cachedDefinitionsRevision = null;
+          this.scheduleDebouncedRefresh();
+        },
+        cacheEtagIfPresent: (etag) => this.cacheDefinitionsRevision(etag)
+      }
+    );
+  }
+  evaluateGateEffective(featureKeys, requirement = "all", negate = false, defaultValue = false, entityContext, identityOverride) {
+    if (featureKeys.length === 0) {
+      return !negate;
+    }
+    const checks = featureKeys.map((key) => {
+      const enabled = this.getEffectiveFlag(
+        key,
+        defaultValue,
+        entityContext,
+        identityOverride
+      );
+      this.recordCheckForKey(key, enabled, identityOverride);
+      return enabled;
+    });
+    let result;
+    if (requirement === "any") {
+      result = checks.some(Boolean);
+    } else {
+      result = checks.every(Boolean);
+    }
+    return negate ? !result : result;
+  }
+  /**
+   * Whether the WebSocket connection is active
+   */
+  get isWsConnected() {
+    return this.wsConnected;
+  }
+  /**
+   * Initialize the client by fetching feature definitions.
+   * When already initialized, rebinds identity (including clearing it) and
+   * re-snapshots flags without re-fetching (definitions are identity-agnostic).
+   * Concurrent cold starts share one fetch; each caller still receives a
+   * request-local snapshot for its identity.
+   */
+  async init(identity) {
+    const wasWarm = this.initialized && this.definitions.size > 0;
+    if (!wasWarm) {
+      if (!this.definitionsLoadPromise) {
+        this.definitionsLoadPromise = (async () => {
+          await this.fetchFlags();
+          this.initialized = true;
+          this.startWebSocket();
+        })().finally(() => {
+          this.definitionsLoadPromise = null;
+        });
+      }
+      await this.definitionsLoadPromise;
+      if (identity) {
+        await this.executeBeforeIdentify(identity);
+        await this.executeAfterIdentify(identity);
+      }
+    }
+    this.identity = identity;
+    this.flags = this.snapshotFlags({ identity });
+    if (wasWarm) {
+      this.logger.debug("Client already initialized; re-snapshotted for identity.");
+    }
+    return this.flags;
+  }
+  /**
+   * Fetch feature definitions from the API (definitions-signed; no identity query).
+   * Counts one definition-refresh hit/miss per performed attempt; concurrent
+   * in-flight joiners await the same fetch and are not counted.
+   */
+  async fetchFlags(identity) {
+    if (identity !== void 0) {
+      this.identity = identity;
+    }
+    if (this.definitionsFetchInFlight) {
+      return this.definitionsFetchInFlight;
+    }
+    this.definitionsFetchInFlight = this.performDefinitionsFetch();
+    try {
+      return await this.definitionsFetchInFlight;
+    } finally {
+      this.definitionsFetchInFlight = null;
+    }
+  }
+  async performDefinitionsFetch() {
+    if (!this.config.appKey) {
+      this.logger.debug("No appKey, using featureDefaults.");
+      this.definitions = /* @__PURE__ */ new Map();
+      this.flags = this.config.featureDefaults ?? {};
+      return this.flags;
+    }
+    let outcomeRecorded = false;
+    try {
+      const pin = this.pendingDefinitionsPin;
+      this.pendingDefinitionsPin = null;
+      const url = appendDefinitionsRevisionParam(
+        buildDefinitionsUrl(this.config),
+        pin
+      );
+      this.logger.debug(`Fetching definitions from: ${url}`);
+      const previousRevision = pin ? null : this.getDefinitionsRevision();
+      const headers = buildDefinitionFetchHeaders(
+        previousRevision ? { "If-None-Match": previousRevision } : {}
+      );
+      const response = await fetchWithTimeout(url, { headers }, this.config.timeout);
+      const responseRevision = this.normalizeDefinitionsRevision(
+        extractDefinitionsRevision(response)
+      );
+      if (response.status === 304) {
+        if (responseRevision) {
+          this.cacheDefinitionsRevision(responseRevision);
+        }
+        this.noteDefinitionCacheHit();
+        outcomeRecorded = true;
+        this.logger.debug("Definitions unchanged (304)");
+        return this.flags;
+      }
+      if (!response.ok) {
+        throw new TogglyNetworkError(
+          `HTTP ${response.status}: ${response.statusText}`
+        );
+      }
+      const bodyText = await readResponseBody(response);
+      const parsed = await parseEvaluatedResponseBody(bodyText, {
+        verifySignatures: this.config.verifySignatures,
+        baseUrl: this.config.baseUrl ?? "https://definitions.toggly.io",
+        allowedKeyIds: this.config.allowedKeyIds,
+        maxSignatureAgeSeconds: this.config.maxSignatureAgeSeconds,
+        headers: buildDefinitionFetchHeaders({})
+      });
+      this.definitions = parseDefinitionsPayload(parsed);
+      this.flags = {
+        ...this.config.featureDefaults ?? {},
+        ...snapshotEvaluatedBooleans(this.definitions, this.buildEvalContext())
+      };
+      if (responseRevision) {
+        this.cacheDefinitionsRevision(responseRevision);
+      }
+      this.logger.debug(`Fetched ${this.definitions.size} definitions.`);
+      if (this.definitionsRevisionsMatch(previousRevision, responseRevision)) {
+        this.noteDefinitionCacheHit();
+      } else {
+        this.noteDefinitionCacheMiss();
+      }
+      outcomeRecorded = true;
+      await this.executeAfterRefresh(this.flags);
+      return this.flags;
+    } catch (error) {
+      this.logger.warn("Failed to fetch flags, preserving last-known-good flags when available.", error);
+      this.config.onError?.("Error fetching feature flags", error);
+      if (!outcomeRecorded && this.definitions.size > 0) {
+        this.noteDefinitionCacheHit();
+      }
+      if (Object.keys(this.flags).length === 0) {
+        this.flags = this.config.featureDefaults ?? {};
+      }
+      return this.flags;
+    }
+  }
+  /**
+   * Get all flags
+   */
+  getFlags() {
+    return { ...this.flags };
+  }
+  /**
+   * Check if a feature is enabled
+   */
+  async isEnabled(featureKey, context, defaultValue = false, entity, kind) {
+    const entityContext = normalizeEntityContext(entity, kind);
+    const hookData = await this.executeBeforeEvaluation(featureKey, defaultValue);
+    const result = this.getEffectiveFlag(featureKey, defaultValue, entityContext, context);
+    this.recordCheckForKey(featureKey, result, context);
+    await this.executeAfterEvaluation(featureKey, hookData, result);
+    return result;
+  }
+  registerContext(kind, mapper) {
+    registerContext(kind, mapper);
+  }
+  /**
+   * Check if a feature is disabled
+   */
+  async isDisabled(featureKey, context, defaultValue = true, entity, kind) {
+    return !await this.isEnabled(featureKey, context, !defaultValue, entity, kind);
+  }
+  /**
+   * Evaluate a feature gate (multiple features)
+   */
+  async evaluateGate(featureKeys, requirement = "all", negate = false, defaultValue = false, entity, kind, identityOverride) {
+    const entityContext = normalizeEntityContext(entity, kind);
+    const firstKey = featureKeys[0] ?? "gate";
+    const hookData = await this.executeBeforeEvaluation(firstKey, defaultValue);
+    const result = this.evaluateGateEffective(
+      featureKeys,
+      requirement,
+      negate,
+      defaultValue,
+      entityContext,
+      identityOverride
+    );
+    await this.executeAfterEvaluation(firstKey, hookData, result);
+    return result;
+  }
+  /**
+   * Get the server context for client hydration
+   */
+  getServerContext() {
+    return {
+      flags: this.flags,
+      appKey: this.config.appKey,
+      environment: this.config.environment,
+      fetchedAt: Date.now()
+    };
+  }
+  // WebSocket live updates
+  /**
+   * Start WebSocket connection for live updates
+   */
+  startWebSocket() {
+    if (!this.config.appKey) {
+      return;
+    }
+    if (this.ws) {
+      return;
+    }
+    const baseUrl = this.config.baseUrl ?? "https://definitions.toggly.io";
+    const wsUrl = buildWebSocketUrl(baseUrl, this.config.appKey, this.getDefinitionsRevision());
+    this.logger.debug(`WebSocket connecting to: ${wsUrl}`);
+    try {
+      this.ws = new WebSocket(wsUrl);
+      this.ws.on("open", () => {
+        this.wsConnected = true;
+        this.wsReconnectAttempt = 0;
+        this.logger.debug("WebSocket connected");
+      });
+      this.ws.on("message", (data) => {
+        const text = data.toString();
+        if (text === "update" || text === "flags-updated") {
+          this.scheduleDebouncedRefresh();
+          return;
+        }
+        try {
+          const message = JSON.parse(text);
+          if (message.type === "ping") {
+            return;
+          }
+          if (message.type === "sync") {
+            this.handleWsSyncMessage(message);
+            return;
+          }
+          if (message.type === "flags-updated" || message.type === "update" || message.type === "signing-key-updated") {
+            this.handleWsUpdateMessage(message);
+          }
+        } catch {
+        }
+      });
+      this.ws.on("close", () => {
+        this.wsConnected = false;
+        this.ws = null;
+        this.logger.debug("WebSocket disconnected, scheduling reconnect");
+        this.scheduleReconnect();
+      });
+      this.ws.on("error", (error) => {
+        this.logger.error("WebSocket error:", error.message);
+      });
+    } catch (error) {
+      this.logger.error("Failed to create WebSocket:", error);
+      this.ws = null;
+      this.scheduleReconnect();
+    }
+  }
+  /**
+   * Schedule WebSocket reconnection
+   */
+  scheduleReconnect() {
+    if (this.wsReconnectTimer) {
+      return;
+    }
+    const delay = getNextReconnectDelayMs(this.wsReconnectAttempt);
+    this.wsReconnectAttempt += 1;
+    this.wsReconnectTimer = setTimeout(() => {
+      this.wsReconnectTimer = null;
+      this.startWebSocket();
+    }, delay);
+  }
+  /**
+   * Stop WebSocket connection and cleanup
+   */
+  stopWebSocket() {
+    if (this.wsReconnectTimer) {
+      clearTimeout(this.wsReconnectTimer);
+      this.wsReconnectTimer = null;
+    }
+    if (this.refreshDebounceTimer) {
+      clearTimeout(this.refreshDebounceTimer);
+      this.refreshDebounceTimer = null;
+    }
+    if (this.ws) {
+      this.ws.removeAllListeners();
+      this.ws.close();
+      this.ws = null;
+      this.wsConnected = false;
+    }
+  }
+  /**
+   * Close the client and cleanup all resources
+   */
+  close() {
+    this.stopWebSocket();
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+    if (this.telemetry) {
+      void this.telemetry.close();
+      this.telemetry = null;
+    }
+    this.logger.debug("TogglyServerClient closed");
+  }
+  /** Record a feature "used" interaction (usage telemetry). */
+  recordUsage(featureKey, identity, variant) {
+    this.telemetry?.recordUsage(featureKey, identity ?? this.identity, variant);
+  }
+  /** Record a feature "viewed" event (usage telemetry). */
+  recordView(featureKey, identity, variant) {
+    this.telemetry?.recordView(featureKey, identity ?? this.identity, variant);
+  }
+  measure(metricKey, value, options) {
+    this.telemetry?.measure(metricKey, value, options);
+  }
+  incrementCounter(metricKey, value = 1, options) {
+    this.telemetry?.incrementCounter(metricKey, value, options);
+  }
+  observe(metricKey, value, options) {
+    this.telemetry?.observe(metricKey, value, options);
+  }
+  async flushTelemetry() {
+    await this.telemetry?.flushAll();
+  }
+  // Hook execution methods
+  async executeBeforeEvaluation(flagKey, defaultValue) {
+    const dataMap = /* @__PURE__ */ new Map();
+    for (const hook of this.hooks) {
+      if (hook.beforeEvaluation) {
+        try {
+          const data = await hook.beforeEvaluation(flagKey, defaultValue);
+          dataMap.set(hook.getMetadata().name, data);
+        } catch (error) {
+          this.logger.error(
+            `Error in hook "${hook.getMetadata().name}.beforeEvaluation":`,
+            error
+          );
+        }
+      }
+    }
+    return dataMap;
+  }
+  async executeAfterEvaluation(flagKey, dataMap, result) {
+    for (let i = this.hooks.length - 1; i >= 0; i--) {
+      const hook = this.hooks[i];
+      if (hook.afterEvaluation) {
+        try {
+          const data = dataMap.get(hook.getMetadata().name);
+          await hook.afterEvaluation(flagKey, data, result);
+        } catch (error) {
+          this.logger.error(
+            `Error in hook "${hook.getMetadata().name}.afterEvaluation":`,
+            error
+          );
+        }
+      }
+    }
+  }
+  async executeBeforeIdentify(identity) {
+    const dataMap = /* @__PURE__ */ new Map();
+    for (const hook of this.hooks) {
+      if (hook.beforeIdentify) {
+        try {
+          const data = await hook.beforeIdentify(identity);
+          dataMap.set(hook.getMetadata().name, data);
+        } catch (error) {
+          this.logger.error(
+            `Error in hook "${hook.getMetadata().name}.beforeIdentify":`,
+            error
+          );
+        }
+      }
+    }
+    return dataMap;
+  }
+  async executeAfterIdentify(identity) {
+    for (let i = this.hooks.length - 1; i >= 0; i--) {
+      const hook = this.hooks[i];
+      if (hook.afterIdentify) {
+        try {
+          await hook.afterIdentify(identity, void 0);
+        } catch (error) {
+          this.logger.error(
+            `Error in hook "${hook.getMetadata().name}.afterIdentify":`,
+            error
+          );
+        }
+      }
+    }
+  }
+  async executeAfterRefresh(flags) {
+    for (const hook of this.hooks) {
+      if (hook.afterRefresh) {
+        try {
+          await hook.afterRefresh(flags);
+        } catch (error) {
+          this.logger.error(
+            `Error in hook "${hook.getMetadata().name}.afterRefresh":`,
+            error
+          );
+        }
+      }
+    }
+  }
+};
+function createServerClient(config) {
+  return new TogglyServerClient(config);
+}
+
+// src/server/loader.ts
+function resolveIdentityOverride(override) {
+  if (override == null) {
+    return getAmbientEvalOverrides();
+  }
+  if (typeof override === "string") {
+    return mergeIdentityContext(getAmbientEvalOverrides(), {
+      identity: override
+    });
+  }
+  return mergeIdentityContext(getAmbientEvalOverrides(), override);
+}
+function createTogglyLoader(options) {
+  const client = createServerClient(options);
+  return {
+    /**
+     * Get the Toggly client
+     */
+    getClient() {
+      return client;
+    },
+    /**
+     * Load feature flags for a loader function.
+     * Builds ambient EvalContext (identity / groups / claims / request) for
+     * the snapshot. Prefer `run` when calling `client.isEnabled('X')` without
+     * an IdentityContext for the full loader duration.
+     */
+    async load(args) {
+      const ambient = await extractEvalContext(args.request, options);
+      await client.init(ambient.identity);
+      return {
+        flags: client.snapshotFlags(ambient),
+        identity: ambient.identity,
+        appKey: options.appKey,
+        environment: options.environment,
+        fetchedAt: Date.now()
+      };
+    },
+    /**
+     * Bind ambient EvalContext for the full loader duration, then run `fn`.
+     * Prefer this when calling `client.isEnabled('X')` without an IdentityContext.
+     */
+    async run(args, fn) {
+      const ambient = await extractEvalContext(args.request, options);
+      return runWithEvalContext(ambient, async () => {
+        await client.init(ambient.identity);
+        const ctx = {
+          flags: client.snapshotFlags(ambient),
+          identity: ambient.identity,
+          appKey: options.appKey,
+          environment: options.environment,
+          fetchedAt: Date.now(),
+          client
+        };
+        return fn(ctx);
+      });
+    },
+    /**
+     * Create loader data with feature context
+     */
+    async getLoaderData(args, additionalData) {
+      const context = await this.load(args);
+      return {
+        ...additionalData,
+        [TOGGLY_LOADER_KEY]: context
+      };
+    },
+    /**
+     * Check if a feature is enabled.
+     * Ambient EvalContext (from `run` / `load` ALS scope) is merged;
+     * per-call string identity or IdentityContext overrides field-by-field.
+     */
+    async isEnabled(featureKey, defaultValue = false, identityOrContext) {
+      return client.isEnabled(
+        featureKey,
+        resolveIdentityOverride(identityOrContext),
+        defaultValue
+      );
+    },
+    /**
+     * Check if a feature is disabled
+     */
+    async isDisabled(featureKey, defaultValue = true, identityOrContext) {
+      return client.isDisabled(
+        featureKey,
+        resolveIdentityOverride(identityOrContext),
+        defaultValue
+      );
+    },
+    /**
+     * Evaluate a feature gate
+     */
+    async evaluateGate(featureKeys, requirement = "all", negate = false, identityOrContext) {
+      return client.evaluateGate(
+        featureKeys,
+        requirement,
+        negate,
+        false,
+        void 0,
+        void 0,
+        resolveIdentityOverride(identityOrContext)
+      );
+    },
+    /**
+     * Get all flags
+     */
+    getFlags() {
+      return client.getFlags();
+    }
+  };
+}
+async function getFeatureFlags(request, options) {
+  const loader = createTogglyLoader(options);
+  return loader.load({ request, params: {}, context: {} });
+}
+async function isFeatureEnabled2(request, featureKey, options, defaultValue = false) {
+  const loader = createTogglyLoader(options);
+  return loader.run(
+    { request, params: {}, context: {} },
+    async ({ client }) => client.isEnabled(featureKey, void 0, defaultValue)
+  );
+}
+function buildActionContext(client, ambient) {
+  return {
+    client,
+    flags: client.snapshotFlags(ambient),
+    context: ambient,
+    isEnabled: (key, def, override) => client.isEnabled(key, mergeIdentityContext(ambient, override), def),
+    isDisabled: (key, def, override) => client.isDisabled(key, mergeIdentityContext(ambient, override), def),
+    evaluateGate: (keys, req, neg, override) => client.evaluateGate(
+      keys,
+      req,
+      neg,
+      false,
+      void 0,
+      void 0,
+      mergeIdentityContext(ambient, override)
+    )
+  };
+}
+function createFeatureGatedAction(options, handler) {
+  return async (args) => {
+    const { request } = args;
+    const client = createServerClient(options);
+    const ambient = await extractEvalContext(request, options);
+    return runWithEvalContext(ambient, async () => {
+      await client.init(ambient.identity);
+      const togglyContext = buildActionContext(client, ambient);
+      if (options.requiredFeatures) {
+        const featureKeys = Array.isArray(options.requiredFeatures) ? options.requiredFeatures : [options.requiredFeatures];
+        const requirement = options.requirement ?? "all";
+        const isAllowed = await client.evaluateGate(
+          featureKeys,
+          requirement,
+          false,
+          false,
+          void 0,
+          void 0,
+          ambient
+        );
+        if (!isAllowed) {
+          if (options.onFeatureDisabled) {
+            return options.onFeatureDisabled(request, featureKeys);
+          }
+          if (options.redirectTo) {
+            return redirect(options.redirectTo);
+          }
+          return Response.json(
+            {
+              error: options.errorMessage ?? "Feature is not available",
+              featureKeys
+            },
+            { status: options.errorStatus ?? 403 }
+          );
+        }
+      }
+      return handler(args, togglyContext);
+    });
+  };
+}
+function createTogglyAction(options) {
+  const client = createServerClient(options);
+  return {
+    /**
+     * Get the Toggly client
+     */
+    getClient() {
+      return client;
+    },
+    /**
+     * Initialize for an action request.
+     * Returned helpers close over ambient EvalContext so `toggly.isEnabled('X')`
+     * needs no IdentityContext. Prefer `run` when using `client.isEnabled('X')`
+     * directly for the full action duration.
+     */
+    async init(request) {
+      const ambient = await extractEvalContext(request, options);
+      await client.init(ambient.identity);
+      return buildActionContext(client, ambient);
+    },
+    /**
+     * Bind ambient EvalContext and run an action handler.
+     */
+    async run(args, fn) {
+      const ambient = await extractEvalContext(args.request, options);
+      return runWithEvalContext(ambient, async () => {
+        await client.init(ambient.identity);
+        return fn(args, buildActionContext(client, ambient));
+      });
+    },
+    /**
+     * Wrap an action with feature checks
+     */
+    requireFeature(featureKey, handler, onDisabled) {
+      return createFeatureGatedAction(
+        {
+          ...options,
+          requiredFeatures: featureKey,
+          onFeatureDisabled: onDisabled
+        },
+        handler
+      );
+    },
+    /**
+     * Wrap an action with feature gate checks
+     */
+    requireFeatures(featureKeys, requirement, handler, onDisabled) {
+      return createFeatureGatedAction(
+        {
+          ...options,
+          requiredFeatures: featureKeys,
+          requirement,
+          onFeatureDisabled: onDisabled
+        },
+        handler
+      );
+    }
+  };
+}
+function requireFeature(featureKey, options, onDisabled) {
+  return function(handler) {
+    return createFeatureGatedAction(
+      {
+        ...options,
+        requiredFeatures: featureKey,
+        onFeatureDisabled: onDisabled ? () => onDisabled() : void 0
+      },
+      handler
+    );
+  };
+}
+
+export { HEADERS, STORAGE_KEYS, TOGGLY_LOADER_KEY, TogglyConfigError, TogglyError, TogglyNetworkError, TogglyServerClient, TogglyTimeoutError, createFeatureGatedAction, createServerClient, createTogglyAction, createTogglyLoader, extractEvalContext, getAmbientEvalOverrides, getFeatureFlags, isFeatureEnabled2 as isFeatureEnabled, mergeIdentityContext, requireFeature, runWithEvalContext };
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map