@lunora/flags 0.0.1 → 1.0.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+import { a as FlagsConfig, b as FlagsDefinition, L as LunoraFlags } from "./packem_shared/types.d-BWygZiSc.mjs";
+export type { c as FlagsAuth, F as FlagsProviderFactory } from "./packem_shared/types.d-BWygZiSc.mjs";
+import { Hook, Logger, Provider } from '@openfeature/server-sdk';
+export type { EvaluationContext, EvaluationDetails, Hook, JsonValue, Logger, Provider } from '@openfeature/server-sdk';
+/**
+* Declare the feature-flag provider for a Lunora app. Pure validation +
+* branding — codegen discovers the default export of `lunora/flags.ts`, imports
+* it into the generated worker, and wires `ctx.flags` from `provider` /
+* `identify` (mirrors how `defineQueue` / `defineWorkflow` feed codegen).
+*
+* ```ts
+* // lunora/flags.ts
+* import { defineFlags } from "@lunora/flags";
+* import { flagshipProvider } from "@lunora/flags/providers/flagship";
+*
+* export default defineFlags({
+*     provider: flagshipProvider({ binding: "FLAGS" }), // Cloudflare Flagship (binding mode)
+*     identify: (auth) => auth.userId ?? undefined,      // default targetingKey
+* });
+* ```
+*
+* Any OpenFeature provider works — Flagship is just the first-class default:
+*
+* ```ts
+* export default defineFlags({ provider: (env) => new SomeOpenFeatureProvider(env.SOME_KEY) });
+* ```
+*/
+declare const defineFlags: (config: FlagsConfig) => FlagsDefinition;
+/** True when a value is a {@link defineFlags} result (the runtime brand check). */
+declare const isFlagsDefinition: (value: unknown) => value is FlagsDefinition;
+/** Options for `createFlags`. Built by codegen from `defineFlags(...)`. */
+interface CreateFlagsOptions {
+  /** OpenFeature hooks applied when the provider is bound. */
+  hooks?: Hook[];
+  /** Logger for the OpenFeature client. */
+  logger?: Logger;
+  /** Lazily constructs the OpenFeature provider from `env` (invoked once per isolate). */
+  provider: () => Provider;
+  /**
+  * Default `targetingKey` for every evaluation (from `defineFlags({ identify })`).
+  * May be a thunk — codegen passes one wrapping the user's `identify` — so a
+  * throwing `identify` fails open to no `targetingKey` rather than escaping
+  * ctx construction and taking down the whole request.
+  */
+  targetingKey?: (() => string | undefined) | string;
+}
+/**
+* Builds the `ctx.flags` facade for a single request. Evaluations resolve
+* through the OpenFeature client (the SDK applies hooks and never throws —
+* provider errors surface as the default value with an `errorCode`). The default
+* `targetingKey` is merged under any per-call context, and identical evaluations
+* within the request are memoized so repeated reads of the same flag are
+* internally consistent and hit the provider once.
+*/
+declare const createFlags: (options: CreateFlagsOptions) => LunoraFlags;
+export { type CreateFlagsOptions, type FlagsConfig, type FlagsDefinition, type LunoraFlags, createFlags, defineFlags, isFlagsDefinition };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { a as FlagsConfig, b as FlagsDefinition, L as LunoraFlags } from "./packem_shared/types.d-BWygZiSc.js";
+export type { c as FlagsAuth, F as FlagsProviderFactory } from "./packem_shared/types.d-BWygZiSc.js";
+import { Hook, Logger, Provider } from '@openfeature/server-sdk';
+export type { EvaluationContext, EvaluationDetails, Hook, JsonValue, Logger, Provider } from '@openfeature/server-sdk';
+/**
+* Declare the feature-flag provider for a Lunora app. Pure validation +
+* branding — codegen discovers the default export of `lunora/flags.ts`, imports
+* it into the generated worker, and wires `ctx.flags` from `provider` /
+* `identify` (mirrors how `defineQueue` / `defineWorkflow` feed codegen).
+*
+* ```ts
+* // lunora/flags.ts
+* import { defineFlags } from "@lunora/flags";
+* import { flagshipProvider } from "@lunora/flags/providers/flagship";
+*
+* export default defineFlags({
+*     provider: flagshipProvider({ binding: "FLAGS" }), // Cloudflare Flagship (binding mode)
+*     identify: (auth) => auth.userId ?? undefined,      // default targetingKey
+* });
+* ```
+*
+* Any OpenFeature provider works — Flagship is just the first-class default:
+*
+* ```ts
+* export default defineFlags({ provider: (env) => new SomeOpenFeatureProvider(env.SOME_KEY) });
+* ```
+*/
+declare const defineFlags: (config: FlagsConfig) => FlagsDefinition;
+/** True when a value is a {@link defineFlags} result (the runtime brand check). */
+declare const isFlagsDefinition: (value: unknown) => value is FlagsDefinition;
+/** Options for `createFlags`. Built by codegen from `defineFlags(...)`. */
+interface CreateFlagsOptions {
+  /** OpenFeature hooks applied when the provider is bound. */
+  hooks?: Hook[];
+  /** Logger for the OpenFeature client. */
+  logger?: Logger;
+  /** Lazily constructs the OpenFeature provider from `env` (invoked once per isolate). */
+  provider: () => Provider;
+  /**
+  * Default `targetingKey` for every evaluation (from `defineFlags({ identify })`).
+  * May be a thunk — codegen passes one wrapping the user's `identify` — so a
+  * throwing `identify` fails open to no `targetingKey` rather than escaping
+  * ctx construction and taking down the whole request.
+  */
+  targetingKey?: (() => string | undefined) | string;
+}
+/**
+* Builds the `ctx.flags` facade for a single request. Evaluations resolve
+* through the OpenFeature client (the SDK applies hooks and never throws —
+* provider errors surface as the default value with an `errorCode`). The default
+* `targetingKey` is merged under any per-call context, and identical evaluations
+* within the request are memoized so repeated reads of the same flag are
+* internally consistent and hit the provider once.
+*/
+declare const createFlags: (options: CreateFlagsOptions) => LunoraFlags;
+export { type CreateFlagsOptions, type FlagsConfig, type FlagsDefinition, type LunoraFlags, createFlags, defineFlags, isFlagsDefinition };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { defineFlags, isFlagsDefinition } from './packem_shared/defineFlags-DAIO8cWQ.mjs';
+export { createFlags } from './packem_shared/createFlags-BQ8eiIlo.mjs';

package/dist/packem_shared/createFlags-BQ8eiIlo.mjs

@@ -0,0 +1,94 @@
+import { OpenFeature, ErrorCode } from '@openfeature/server-sdk';
+
+const DOMAIN = "lunora";
+let clientBinding;
+const bindClient = ({ hooks, logger, provider }) => {
+  if (clientBinding === void 0) {
+    clientBinding = (async () => {
+      await OpenFeature.setProviderAndWait(DOMAIN, provider());
+      const client = OpenFeature.getClient(DOMAIN);
+      if (logger) {
+        client.setLogger(logger);
+      }
+      if (hooks && hooks.length > 0) {
+        client.addHooks(...hooks);
+      }
+      return client;
+    })();
+    clientBinding.catch(() => {
+      clientBinding = void 0;
+    });
+  }
+  return clientBinding;
+};
+const resetFlags = async () => {
+  clientBinding = void 0;
+  await OpenFeature.clearProviders();
+};
+const memoKey = (type, flagKey, defaultValue, context) => {
+  const entries = Object.keys(context).toSorted((a, b) => a.localeCompare(b)).map((name) => [name, context[name]]);
+  return JSON.stringify([type, flagKey, defaultValue, entries]);
+};
+const resolveDetails = (client, type, flagKey, defaultValue, context) => {
+  switch (type) {
+    case "boolean": {
+      return client.getBooleanDetails(flagKey, defaultValue, context);
+    }
+    case "number": {
+      return client.getNumberDetails(flagKey, defaultValue, context);
+    }
+    case "object": {
+      return client.getObjectDetails(flagKey, defaultValue, context);
+    }
+    case "string": {
+      return client.getStringDetails(flagKey, defaultValue, context);
+    }
+    default: {
+      throw new Error(`createFlags: unknown flag type "${type}"`);
+    }
+  }
+};
+const createFlags = (options) => {
+  const { hooks, logger, provider, targetingKey } = options;
+  let resolvedTargetingKey;
+  try {
+    resolvedTargetingKey = typeof targetingKey === "function" ? targetingKey() : targetingKey;
+  } catch {
+    resolvedTargetingKey = void 0;
+  }
+  const memo = /* @__PURE__ */ new Map();
+  const evaluate = (type, flagKey, defaultValue, context) => {
+    const merged = resolvedTargetingKey === void 0 ? { ...context } : { targetingKey: resolvedTargetingKey, ...context };
+    const key = memoKey(type, flagKey, defaultValue, merged);
+    const cached = memo.get(key);
+    if (cached) {
+      return cached;
+    }
+    const pending = bindClient({ hooks, logger, provider }).then((client) => resolveDetails(client, type, flagKey, defaultValue, merged)).catch((error) => {
+      return {
+        errorCode: ErrorCode.GENERAL,
+        errorMessage: error instanceof Error ? error.message : String(error),
+        flagKey,
+        flagMetadata: {},
+        reason: "ERROR",
+        value: defaultValue
+      };
+    });
+    memo.set(key, pending);
+    return pending;
+  };
+  return {
+    boolean: (flagKey, defaultValue, context) => evaluate("boolean", flagKey, defaultValue, context).then((details) => details.value),
+    details: {
+      boolean: (flagKey, defaultValue, context) => evaluate("boolean", flagKey, defaultValue, context),
+      number: (flagKey, defaultValue, context) => evaluate("number", flagKey, defaultValue, context),
+      object: (flagKey, defaultValue, context) => evaluate("object", flagKey, defaultValue, context),
+      string: (flagKey, defaultValue, context) => evaluate("string", flagKey, defaultValue, context)
+    },
+    number: (flagKey, defaultValue, context) => evaluate("number", flagKey, defaultValue, context).then((details) => details.value),
+    object: (flagKey, defaultValue, context) => evaluate("object", flagKey, defaultValue, context).then((details) => details.value),
+    string: (flagKey, defaultValue, context) => evaluate("string", flagKey, defaultValue, context).then((details) => details.value)
+  };
+};
+
+export { createFlags, resetFlags };

package/dist/packem_shared/defineFlags-DAIO8cWQ.mjs

@@ -0,0 +1,15 @@
+const defineFlags = (config) => {
+  if (typeof config.provider !== "function") {
+    throw new TypeError('defineFlags: `provider` must be a function `(env) => Provider` (e.g. flagshipProvider({ binding: "FLAGS" }))');
+  }
+  if (config.identify !== void 0 && typeof config.identify !== "function") {
+    throw new TypeError("defineFlags: `identify` must be a function `(auth) => string | undefined` when provided");
+  }
+  if (config.hooks !== void 0 && !Array.isArray(config.hooks)) {
+    throw new TypeError("defineFlags: `hooks` must be an array of OpenFeature hooks when provided");
+  }
+  return { ...config, isLunoraFlags: true };
+};
+const isFlagsDefinition = (value) => typeof value === "object" && value !== null && value.isLunoraFlags === true;
+
+export { defineFlags, isFlagsDefinition };

package/dist/packem_shared/types.d-BWygZiSc.d.mts

@@ -0,0 +1,85 @@
+import { Hook, Logger, Provider, EvaluationContext, EvaluationDetails, JsonValue } from '@openfeature/server-sdk';
+/**
+* The flag-evaluation surface spliced onto every Lunora `ctx` as `ctx.flags`
+* (query / mutation / action) by codegen when an app wires `@lunora/flags`.
+*
+* Every method resolves through the configured OpenFeature provider and **never
+* throws** — on a missing flag, type mismatch, provider error, or
+* misconfiguration it resolves with the supplied `defaultValue`. Use the
+* `details.*` variants when you need the full {@link EvaluationDetails} (reason,
+* variant, `errorCode`, `errorMessage`) alongside the value.
+*
+* The optional per-call `context` is merged on top of the default targeting
+* context (the `targetingKey` derived from `defineFlags({ identify })`), so a
+* call can add or override targeting attributes for that single evaluation.
+*/
+interface LunoraFlags {
+  /** Resolve a boolean flag (feature on/off). */
+  boolean: (flagKey: string, defaultValue: boolean, context?: EvaluationContext) => Promise<boolean>;
+  /** Full {@link EvaluationDetails} variants — value plus reason / variant / error metadata. */
+  details: {
+    boolean: (flagKey: string, defaultValue: boolean, context?: EvaluationContext) => Promise<EvaluationDetails<boolean>>;
+    number: (flagKey: string, defaultValue: number, context?: EvaluationContext) => Promise<EvaluationDetails<number>>;
+    object: <T extends JsonValue>(flagKey: string, defaultValue: T, context?: EvaluationContext) => Promise<EvaluationDetails<T>>;
+    string: (flagKey: string, defaultValue: string, context?: EvaluationContext) => Promise<EvaluationDetails<string>>;
+  };
+  /** Resolve a number flag (rate limits, thresholds, percentages). */
+  number: (flagKey: string, defaultValue: number, context?: EvaluationContext) => Promise<number>;
+  /** Resolve an object/JSON flag (complex configuration). */
+  object: <T extends JsonValue>(flagKey: string, defaultValue: T, context?: EvaluationContext) => Promise<T>;
+  /** Resolve a string flag (A/B variants, copy experiments). */
+  string: (flagKey: string, defaultValue: string, context?: EvaluationContext) => Promise<string>;
+}
+/**
+* The resolved request auth handed to {@link FlagsConfig.identify} so an app can
+* derive the default OpenFeature `targetingKey` (usually the authenticated user
+* id). This mirrors the `auth` shape the runtime already threads into other ctx
+* helpers, so `identify` never needs the full ctx.
+*/
+interface FlagsAuth {
+  /** The verified identity claims for the request, or `null` when anonymous. */
+  identity: Record<string, unknown> | null;
+  /** The authenticated user id for the request, or `null` when anonymous. */
+  userId: string | null;
+}
+/**
+* Builds the OpenFeature {@link Provider} for the request from the Worker `env`.
+*
+* Receiving `env` (rather than a constructed provider) is what lets the Flagship
+* binding provider read `env.FLAGS` at request time — matching the existing
+* `config.ai?.(env)` thunk pattern. Construction is memoized per DO isolate, so
+* this factory is invoked once per isolate, not once per request.
+*/
+type FlagsProviderFactory = (env: Record<string, unknown>) => Provider;
+/** Options accepted by `defineFlags`. */
+interface FlagsConfig {
+  /**
+  * OpenFeature hooks run on every evaluation (logging, telemetry, …). Applied
+  * to the Lunora flags client when the provider is bound.
+  */
+  hooks?: Hook[];
+  /**
+  * Derives the default OpenFeature `targetingKey` from the request auth. Most
+  * apps return the user id: `identify: (auth) => auth.userId ?? undefined`.
+  * A per-call `context.targetingKey` still overrides this.
+  */
+  identify?: (auth: FlagsAuth) => string | undefined;
+  /** Logger for the OpenFeature client (provider + SDK diagnostics). */
+  logger?: Logger;
+  /**
+  * The OpenFeature provider factory. Use `flagshipProvider(...)` from
+  * `@lunora/flags/providers/flagship`, or return any OpenFeature provider:
+  * `provider: (env) => new LaunchDarklyProvider(env.LD_KEY)`.
+  */
+  provider: FlagsProviderFactory;
+}
+/**
+* A branded {@link FlagsConfig} produced by `defineFlags`. This is the
+* default export of `lunora/flags.ts`; codegen imports it into the generated
+* worker and wires `ctx.flags` from its `provider` / `identify`.
+*/
+interface FlagsDefinition extends FlagsConfig {
+  /** Runtime brand used by `isFlagsDefinition` and codegen discovery. */
+  readonly isLunoraFlags: true;
+}
+export { FlagsProviderFactory as F, LunoraFlags as L, FlagsConfig as a, FlagsDefinition as b, FlagsAuth as c };

package/dist/packem_shared/types.d-BWygZiSc.d.ts

@@ -0,0 +1,85 @@
+import { Hook, Logger, Provider, EvaluationContext, EvaluationDetails, JsonValue } from '@openfeature/server-sdk';
+/**
+* The flag-evaluation surface spliced onto every Lunora `ctx` as `ctx.flags`
+* (query / mutation / action) by codegen when an app wires `@lunora/flags`.
+*
+* Every method resolves through the configured OpenFeature provider and **never
+* throws** — on a missing flag, type mismatch, provider error, or
+* misconfiguration it resolves with the supplied `defaultValue`. Use the
+* `details.*` variants when you need the full {@link EvaluationDetails} (reason,
+* variant, `errorCode`, `errorMessage`) alongside the value.
+*
+* The optional per-call `context` is merged on top of the default targeting
+* context (the `targetingKey` derived from `defineFlags({ identify })`), so a
+* call can add or override targeting attributes for that single evaluation.
+*/
+interface LunoraFlags {
+  /** Resolve a boolean flag (feature on/off). */
+  boolean: (flagKey: string, defaultValue: boolean, context?: EvaluationContext) => Promise<boolean>;
+  /** Full {@link EvaluationDetails} variants — value plus reason / variant / error metadata. */
+  details: {
+    boolean: (flagKey: string, defaultValue: boolean, context?: EvaluationContext) => Promise<EvaluationDetails<boolean>>;
+    number: (flagKey: string, defaultValue: number, context?: EvaluationContext) => Promise<EvaluationDetails<number>>;
+    object: <T extends JsonValue>(flagKey: string, defaultValue: T, context?: EvaluationContext) => Promise<EvaluationDetails<T>>;
+    string: (flagKey: string, defaultValue: string, context?: EvaluationContext) => Promise<EvaluationDetails<string>>;
+  };
+  /** Resolve a number flag (rate limits, thresholds, percentages). */
+  number: (flagKey: string, defaultValue: number, context?: EvaluationContext) => Promise<number>;
+  /** Resolve an object/JSON flag (complex configuration). */
+  object: <T extends JsonValue>(flagKey: string, defaultValue: T, context?: EvaluationContext) => Promise<T>;
+  /** Resolve a string flag (A/B variants, copy experiments). */
+  string: (flagKey: string, defaultValue: string, context?: EvaluationContext) => Promise<string>;
+}
+/**
+* The resolved request auth handed to {@link FlagsConfig.identify} so an app can
+* derive the default OpenFeature `targetingKey` (usually the authenticated user
+* id). This mirrors the `auth` shape the runtime already threads into other ctx
+* helpers, so `identify` never needs the full ctx.
+*/
+interface FlagsAuth {
+  /** The verified identity claims for the request, or `null` when anonymous. */
+  identity: Record<string, unknown> | null;
+  /** The authenticated user id for the request, or `null` when anonymous. */
+  userId: string | null;
+}
+/**
+* Builds the OpenFeature {@link Provider} for the request from the Worker `env`.
+*
+* Receiving `env` (rather than a constructed provider) is what lets the Flagship
+* binding provider read `env.FLAGS` at request time — matching the existing
+* `config.ai?.(env)` thunk pattern. Construction is memoized per DO isolate, so
+* this factory is invoked once per isolate, not once per request.
+*/
+type FlagsProviderFactory = (env: Record<string, unknown>) => Provider;
+/** Options accepted by `defineFlags`. */
+interface FlagsConfig {
+  /**
+  * OpenFeature hooks run on every evaluation (logging, telemetry, …). Applied
+  * to the Lunora flags client when the provider is bound.
+  */
+  hooks?: Hook[];
+  /**
+  * Derives the default OpenFeature `targetingKey` from the request auth. Most
+  * apps return the user id: `identify: (auth) => auth.userId ?? undefined`.
+  * A per-call `context.targetingKey` still overrides this.
+  */
+  identify?: (auth: FlagsAuth) => string | undefined;
+  /** Logger for the OpenFeature client (provider + SDK diagnostics). */
+  logger?: Logger;
+  /**
+  * The OpenFeature provider factory. Use `flagshipProvider(...)` from
+  * `@lunora/flags/providers/flagship`, or return any OpenFeature provider:
+  * `provider: (env) => new LaunchDarklyProvider(env.LD_KEY)`.
+  */
+  provider: FlagsProviderFactory;
+}
+/**
+* A branded {@link FlagsConfig} produced by `defineFlags`. This is the
+* default export of `lunora/flags.ts`; codegen imports it into the generated
+* worker and wires `ctx.flags` from its `provider` / `identify`.
+*/
+interface FlagsDefinition extends FlagsConfig {
+  /** Runtime brand used by `isFlagsDefinition` and codegen discovery. */
+  readonly isLunoraFlags: true;
+}
+export { FlagsProviderFactory as F, LunoraFlags as L, FlagsConfig as a, FlagsDefinition as b, FlagsAuth as c };

package/dist/providers/env.d.mts

@@ -0,0 +1,43 @@
+import { F as FlagsProviderFactory } from "../packem_shared/types.d-BWygZiSc.mjs";
+import '@openfeature/server-sdk';
+/** Options for {@link envProvider}. */
+interface EnvProviderOptions {
+  /**
+  * Map a flag key to its Worker `env` variable name. Defaults to
+  * `prefix` + the key upper-snake-cased (`"dark-mode"` → `"FLAG_DARK_MODE"`).
+  * Provide this to override the whole derivation (the `prefix` is then unused).
+  */
+  name?: (flagKey: string) => string;
+  /** Prefix prepended to the derived env variable name. Defaults to `"FLAG_"`. */
+  prefix?: string;
+}
+/**
+* A zero-dependency OpenFeature provider that reads flags from the Worker `env`
+* (plain `vars` and Secrets Store / `.dev.vars` values). Each flag key maps to an
+* env variable (default `"dark-mode"` → `env.FLAG_DARK_MODE`); the string value is
+* coerced to the read's type:
+*
+* - **boolean** — `true`/`1`/`on`/`yes` → `true`, `false`/`0`/`off`/`no` → `false` (case-insensitive), anything else is a parse error.
+* - **number** — `Number(value)`; non-numeric is a parse error.
+* - **string** — the raw value.
+* - **object** — `JSON.parse(value)`; invalid JSON is a parse error.
+*
+* A key with no matching env variable falls back to the call's default (reason
+* `DEFAULT`); a parse error also returns the default (reason `ERROR`) so a
+* malformed value degrades the read rather than throwing.
+*
+* ```ts
+* import { defineFlags } from "@lunora/flags";
+* import { envProvider } from "@lunora/flags/providers/env";
+*
+* // wrangler.jsonc: { "vars": { "FLAG_DARK_MODE": "true", "FLAG_PAGE_SIZE": "25" } }
+* export default defineFlags({ provider: envProvider() });
+* // ctx.flags.boolean("dark-mode", false) → true
+* // ctx.flags.number("page-size", 10)     → 25
+* ```
+*
+* Values are static per deployment (env is fixed for the isolate's lifetime), so
+* this suits build-time/per-environment toggles rather than live targeting.
+*/
+declare const envProvider: (options?: EnvProviderOptions) => FlagsProviderFactory;
+export { type EnvProviderOptions, envProvider };

package/dist/providers/env.d.ts

@@ -0,0 +1,43 @@
+import { F as FlagsProviderFactory } from "../packem_shared/types.d-BWygZiSc.js";
+import '@openfeature/server-sdk';
+/** Options for {@link envProvider}. */
+interface EnvProviderOptions {
+  /**
+  * Map a flag key to its Worker `env` variable name. Defaults to
+  * `prefix` + the key upper-snake-cased (`"dark-mode"` → `"FLAG_DARK_MODE"`).
+  * Provide this to override the whole derivation (the `prefix` is then unused).
+  */
+  name?: (flagKey: string) => string;
+  /** Prefix prepended to the derived env variable name. Defaults to `"FLAG_"`. */
+  prefix?: string;
+}
+/**
+* A zero-dependency OpenFeature provider that reads flags from the Worker `env`
+* (plain `vars` and Secrets Store / `.dev.vars` values). Each flag key maps to an
+* env variable (default `"dark-mode"` → `env.FLAG_DARK_MODE`); the string value is
+* coerced to the read's type:
+*
+* - **boolean** — `true`/`1`/`on`/`yes` → `true`, `false`/`0`/`off`/`no` → `false` (case-insensitive), anything else is a parse error.
+* - **number** — `Number(value)`; non-numeric is a parse error.
+* - **string** — the raw value.
+* - **object** — `JSON.parse(value)`; invalid JSON is a parse error.
+*
+* A key with no matching env variable falls back to the call's default (reason
+* `DEFAULT`); a parse error also returns the default (reason `ERROR`) so a
+* malformed value degrades the read rather than throwing.
+*
+* ```ts
+* import { defineFlags } from "@lunora/flags";
+* import { envProvider } from "@lunora/flags/providers/env";
+*
+* // wrangler.jsonc: { "vars": { "FLAG_DARK_MODE": "true", "FLAG_PAGE_SIZE": "25" } }
+* export default defineFlags({ provider: envProvider() });
+* // ctx.flags.boolean("dark-mode", false) → true
+* // ctx.flags.number("page-size", 10)     → 25
+* ```
+*
+* Values are static per deployment (env is fixed for the isolate's lifetime), so
+* this suits build-time/per-environment toggles rather than live targeting.
+*/
+declare const envProvider: (options?: EnvProviderOptions) => FlagsProviderFactory;
+export { type EnvProviderOptions, envProvider };

package/dist/providers/env.mjs

@@ -0,0 +1,75 @@
+import { ErrorCode } from '@openfeature/server-sdk';
+
+const upperSnake = (flagKey) => flagKey.replaceAll(/[^a-z0-9]+/gi, "_").toUpperCase();
+const TRUE_TOKENS = /* @__PURE__ */ new Set(["1", "on", "true", "yes"]);
+const FALSE_TOKENS = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+const staticDetails = (value) => Promise.resolve({ reason: "STATIC", value });
+const missing = (defaultValue) => Promise.resolve({ reason: "DEFAULT", value: defaultValue });
+const parseError = (defaultValue, message) => Promise.resolve({ errorCode: ErrorCode.PARSE_ERROR, errorMessage: message, reason: "ERROR", value: defaultValue });
+const envProvider = (options = {}) => {
+  const prefix = options.prefix ?? "FLAG_";
+  const nameOf = options.name ?? ((flagKey) => prefix + upperSnake(flagKey));
+  return (env) => {
+    const raw = (flagKey) => {
+      const value = env[nameOf(flagKey)];
+      if (value === void 0 || value === null) {
+        return void 0;
+      }
+      if (typeof value === "string") {
+        return value;
+      }
+      if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+      }
+      return JSON.stringify(value);
+    };
+    return {
+      metadata: { name: "lunora-env" },
+      resolveBooleanEvaluation: (flagKey, defaultValue) => {
+        const value = raw(flagKey);
+        if (value === void 0) {
+          return missing(defaultValue);
+        }
+        const token = value.trim().toLowerCase();
+        if (TRUE_TOKENS.has(token)) {
+          return staticDetails(true);
+        }
+        if (FALSE_TOKENS.has(token)) {
+          return staticDetails(false);
+        }
+        return parseError(defaultValue, `env flag "${flagKey}" (${nameOf(flagKey)}) is not a boolean: "${value}"`);
+      },
+      resolveNumberEvaluation: (flagKey, defaultValue) => {
+        const value = raw(flagKey);
+        if (value === void 0) {
+          return missing(defaultValue);
+        }
+        const parsed = Number(value);
+        if (value.trim() === "" || Number.isNaN(parsed)) {
+          return parseError(defaultValue, `env flag "${flagKey}" (${nameOf(flagKey)}) is not a number: "${value}"`);
+        }
+        return staticDetails(parsed);
+      },
+      resolveObjectEvaluation: (flagKey, defaultValue) => {
+        const value = raw(flagKey);
+        if (value === void 0) {
+          return missing(defaultValue);
+        }
+        try {
+          return staticDetails(JSON.parse(value));
+        } catch (error) {
+          return parseError(
+            defaultValue,
+            `env flag "${flagKey}" (${nameOf(flagKey)}) is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      },
+      resolveStringEvaluation: (flagKey, defaultValue) => {
+        const value = raw(flagKey);
+        return value === void 0 ? missing(defaultValue) : staticDetails(value);
+      }
+    };
+  };
+};
+
+export { envProvider };

package/dist/providers/flagship.d.mts

@@ -0,0 +1,62 @@
+import { F as FlagsProviderFactory } from "../packem_shared/types.d-BWygZiSc.mjs";
+import '@openfeature/server-sdk';
+/**
+* Flagship provider in **binding mode** (recommended for Workers): evaluations
+* go through the wrangler binding — no HTTP, no auth token.
+*/
+interface FlagshipBindingOptions {
+  /**
+  * The name of the Flagship binding on the Worker `env` (e.g. `"FLAGS"`). The
+  * factory resolves `env[binding]` at request time. Configure a matching
+  * `flagship` binding in `wrangler.jsonc` with this binding name and your app id.
+  */
+  binding: string;
+  /** Max cached entries when `cacheTtl` is set (default 1000). */
+  cacheMaxSize?: number;
+  /** Opt-in per-context TTL cache, in ms. Enables caching when greater than 0. */
+  cacheTtl?: number;
+  /** Surface Flagship SDK logs (default false). */
+  logging?: boolean;
+}
+/**
+* Flagship provider in **HTTP mode** (non-binding Workers or other server
+* runtimes): evaluations go to the Flagship API over HTTP.
+*/
+interface FlagshipHttpOptions {
+  /** Account id for multi-tenant routing (required with `appId`). */
+  accountId?: string;
+  /** Flagship app id; the SDK builds the evaluation URL (mutually exclusive with `endpoint`). */
+  appId?: string;
+  /** Bearer token added as an `Authorization: Bearer` header to every request. */
+  authToken?: string;
+  /** Base URL override (only used with `appId`). */
+  baseUrl?: string;
+  cacheMaxSize?: number;
+  cacheTtl?: number;
+  /** Full evaluation URL (mutually exclusive with `appId`). */
+  endpoint?: string;
+  logging?: boolean;
+  /** Retry attempts on transient errors (default 1, max 10). */
+  retries?: number;
+  /** Delay between retries in ms (default 1000, max 30000). */
+  retryDelay?: number;
+  /** Request timeout in ms (default 5000). */
+  timeout?: number;
+}
+/** Options for `flagshipProvider` — binding mode or HTTP mode. */
+type FlagshipProviderOptions = FlagshipBindingOptions | FlagshipHttpOptions;
+/**
+* Builds a Cloudflare Flagship OpenFeature provider for `defineFlags({ provider })`.
+* Flagship is Lunora's first-class default; the same `defineFlags` accepts any
+* OpenFeature provider, so apps can swap it out without touching call sites.
+*
+* ```ts
+* // Binding mode (recommended) — reads env.FLAGS at request time:
+* flagshipProvider({ binding: "FLAGS" })
+*
+* // HTTP mode:
+* flagshipProvider({ appId: "app-abc", accountId: "acct", authToken: "tok" })
+* ```
+*/
+declare const flagshipProvider: (options: FlagshipProviderOptions) => FlagsProviderFactory;
+export { type FlagshipBindingOptions, type FlagshipHttpOptions, type FlagshipProviderOptions, flagshipProvider };