@ogygia/flags 0.0.0 → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Puru Vijayvargia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
 # @ogygia/flags
 
-Reserved for [ogygia](https://ogygia.puruvj.dev). The first release is on its way.
+Feature flags and A/B tests for [ogygia](https://ogygiajs.dev). A kill switch, a rollout, a targeting rule and an A/B/n test are one primitive, `flag()`. It is decided on the server during SSR, so the chosen variant is simply what renders: no flicker, no client SDK, no JS for the decision.
+
+## Install
+
+```bash
+pnpm add @ogygia/flags
+```
+
+```ts
+// vite.config.ts
+import { ogygia } from 'ogygia/vite';
+import { flags } from '@ogygia/flags/vite';
+
+export default defineConfig({
+	plugins: [ogygia(), flags(), sveltekit()]
+});
+```
+
+## Use
+
+```ts
+import { flag, decide } from '@ogygia/flags';
+
+export const checkout = flag('new-checkout');               // kill switch
+export const hero = flag('hero', { control: 80, bold: 20 }); // weighted variants
+
+hero(c); // 'control' | 'bold', sticky per visitor
+```
+
+A native `flag()` works without the plugin. The plugin primes a `decide({ source })` (OpenFeature, OFREP, or your own function) one time per request, and drains the `exposure` sink at the end of each request. OpenFeature lives at `@ogygia/flags/openfeature`.
+
+Docs: [Flags & experiments](https://ogygiajs.dev/docs/app/experiments).

package/dist/app.d.ts

@@ -0,0 +1,3 @@
+import { ServerApp } from "@ogygia/core/plugin";
+export declare function set_flags_app(app: ServerApp | null): void;
+export declare function flags_app(): ServerApp | null;

package/dist/app.js

@@ -0,0 +1,9 @@
+// src/app.ts
+let current = null;
+function set_flags_app(app) {
+	current = app;
+}
+function flags_app() {
+	return current;
+}
+export { flags_app, set_flags_app };

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import { StandardSchemaV1 } from "@ogygia/core/plugin/utils";
+export type CtxLike = {
+  request: Request;
+  url: URL;
+  cookies?: {
+    get(name: string): string | undefined;
+  };
+  /** The router's ONE identity (`routes(table, { visitor })`) — read first when present. Open
+   *  shape (matches the router's `Visitor`): a targeting fn reads app claims off it. */
+  visitor?: (Record<string, unknown> & {
+    sub?: string;
+  }) | undefined;
+};
+/** One decided flag from the SOURCE: a variant name (validated against the flag's declared
+ *  variants), optionally with a vendor-authored value (validated against the flag's `value`
+ *  schema). A bare boolean/string is accepted too — sugar for `{ variant }`. */
+export type Resolved = {
+  variant: string;
+  value?: unknown;
+} | string | boolean;
+/** What the source is asked to decide — the app's flags for this request. */
+export interface FlagQuery {
+  name: string;
+  variants: readonly string[];
+  /** `'boolean'` for a kill switch / rollout / targeting flag, `'variant'` for a weighted set. */
+  kind: "boolean" | "variant";
+}
+/** A decision source — OpenFeature, OFREP, or any function. Given the app's flags + the request
+ *  context, return each flag's decision (missing keys fall through to the native rule). Resolved
+ *  ONCE per request (awaited by `handle()` / the router), so every read stays sync. */
+export type FlagSource = (queries: FlagQuery[], c: CtxLike) => Record<string, Resolved> | Promise<Record<string, Resolved>>;
+export interface ExposureEvent {
+  name: string;
+  variant: string;
+  /** the sticky identity the decision keyed on (undefined = anonymous) */
+  sub?: string;
+  at: number;
+}
+export interface DecideOptions {
+  /** Where decisions come from (a vendor). Omit for pure-native flags (still sticky + zero-JS). */
+  source?: FlagSource;
+  /** Honor `?og-exp=name:variant` beyond dev — gate on something a visitor can't forge (a session
+   *  role, a signed QA cookie). Default: dev only. */
+  overrides?: (c: CtxLike) => boolean;
+  /** Exposure sink — called with a BATCH of events (batching is built in: flushed at `max`
+   *  events, after `ms`, or at each request's end). A throwing sink never breaks a request. */
+  exposure?: (events: ExposureEvent[]) => void | Promise<void>;
+  /** Exposure batch size / age caps. Defaults: `max` 25, `ms` 2000. */
+  batch?: {
+    max?: number;
+    ms?: number;
+  };
+}
+/**
+ * Configure flags for this server, once (hooks.server.ts / any server module). Everything is
+ * optional — with no `decide()` at all, flags are native, sticky, and zero-JS.
+ *
+ *   decide({ source: openfeature(client), overrides: (c) => !!c.visitor?.qa, exposure: send });
+ */
+export declare function decide(opts: DecideOptions): void;
+/** Drain queued exposures to the sink. Called at each request's end (serverless-safe tail) and on
+ *  the size/age caps. A sink failure is contained — a lost batch is never a request's problem. */
+export declare function flush_exposures(): void;
+/**
+ * Resolve the source ONCE per request over every registered flag, caching decisions on the
+ * Request so reads stay sync. Awaited by the flags plugin's `request` stage (flags/server.ts), above
+ * the page / hole split. Idempotent; a no-op without a source. Never throws — a source failure
+ * degrades every flag to its native rule, it does not take the request down.
+ */
+export declare function prime_flags(c: CtxLike): Promise<void>;
+/** A per-request component chooser for `page()` — `page(hero.pick({ control: A, bold: B }))`.
+ *  Branded (not a bare function) because Svelte 5 components ARE functions. */
+export interface ComponentPick {
+  __ogpick: (c: CtxLike) => unknown;
+}
+/** Rare knobs (third arg to `flag`). */
+export interface FlagOptions<Value = unknown> {
+  /** Mutual-exclusion group. Members sharing a `layer` string split visitors into equal LANES:
+   *  one sticky hash of (group, visitor) over the sorted member names picks each visitor's
+   *  OWNER, and every other member answers control before its own rule runs — two experiments
+   *  on one surface never share a visitor, so their measurements stay attributable. Real
+   *  exposure = a member's split ÷ member count. Override/carried/source outrank the gate. */
+  layer?: string;
+  /** Standard Schema for a vendor-authored payload read via `.value(c)`. A vendor value that
+   *  fails the schema is IGNORED (never enters) — the same trust-boundary law as body schemas. */
+  value?: StandardSchemaV1<Value>;
+  /** Required alongside `value`: the payload when the source is silent or a value is invalid, so
+   *  `.value(c)` never returns undefined. */
+  fallback?: Value;
+}
+/** The shape a flag is declared with (second arg):
+ *  - omitted → a kill switch (off until decided on),
+ *  - a number → sticky rollout percent (0–100) of the feature,
+ *  - a function → per-request targeting (`true`/`false`, or `undefined` to fall through),
+ *  - a record → weighted variants (ratios; the first key is control). */
+export type FlagShape<V extends string> = undefined | number | ((c: CtxLike) => boolean | undefined) | Record<V, number>;
+interface FlagBase<Value> {
+  readonly name: string;
+  /** `name:variant` — for `data-og-exp` stamps, logs, Server-Timing labels. */
+  stamp(c: CtxLike): string;
+  /** Vendor-authored payload (validated by the `value` schema), else the `fallback`. */
+  value(c: CtxLike): Value;
+}
+/** A boolean flag — calling it answers "does this request get the feature?". */
+export interface BoolFlag<Value = unknown> extends FlagBase<Value> {
+  (c: CtxLike): boolean;
+  readonly variants: readonly ("off" | "on")[];
+  /** Page slot (no `c` — the router supplies it): `page(flag.pick({ … }))`. */
+  pick(map: Record<"off" | "on", unknown>): ComponentPick;
+  /** Pick this visitor's entry from a per-variant map (`'off' | 'on'`), typed + total. */
+  pick<T>(c: CtxLike, map: Record<"off" | "on", T>): T;
+}
+/** A weighted-variant flag — calling it answers which variant this request gets. */
+export interface VariantFlag<V extends string, Value = unknown> extends FlagBase<Value> {
+  (c: CtxLike): V;
+  readonly variants: readonly V[];
+  /** Page slot (no `c` — the router supplies it): `page(flag.pick({ … }))`. */
+  pick(map: Record<V, unknown>): ComponentPick;
+  /** Pick this visitor's entry from a per-variant map, typed + total. */
+  pick<T>(c: CtxLike, map: Record<V, T>): T;
+}
+export declare function flag<V extends string, Value = unknown>(name: string, shape: Record<V, number>, opts?: FlagOptions<Value>): VariantFlag<V, Value>;
+export declare function flag<Value = unknown>(name: string, shape?: number | ((c: CtxLike) => boolean | undefined), opts?: FlagOptions<Value>): BoolFlag<Value>;
+export {};

package/dist/index.js

@@ -0,0 +1,274 @@
+import { flags_app } from "./app.js";
+import { BROWSER, DEV } from "esm-env";
+import { fnv1a32 } from "@ogygia/core/plugin/utils";
+// src/index.ts
+/**
+* `flag()` — the ONE assignment primitive. A kill switch, a rollout, a targeting rule, and an
+* A/B/n test are the same thing: a name with variants, decided per visitor. This module owns the
+* DECISION only; branching rides `flag.pick()` (a router page slot, or a value map), measurement
+* rides the exposure sink, and vendor integration rides `decide({ source })`.
+*
+* Decision order per request (deterministic, sticky, ZERO-JS — it runs server-side during SSR and
+* the chosen variant is simply what gets rendered, so csr=false pages A/B for free):
+*   ?og-exp override (gated) → carried claims (a shell decided upstream) → the SOURCE
+*   (OpenFeature / OFREP / any resolver, primed once per request) → the native rule
+*   (targeting fn / weights) → the first variant (control / off).
+*
+* Everything the old surface split across `experiment` / `flag` / `layer` / `allowOverrides` /
+* `onExposure` / `batchExposures` / `.bucket` / `.on` / `.stamp` collapses to: `flag()`, calling
+* it, `.pick()`, `.value()`, and one `decide()`.
+*/
+/** Written by an upstream shell's identity hop (the fragment feature); absent = the tier is skipped. */
+const CLAIMS = Symbol.for("ogygia.claims.v1");
+/** Per-request source resolution, cached on the Request (GC'd with it). */
+const RESOLVED = Symbol.for("ogygia.flags.resolved.v1");
+/** 0..9999 — sticky hash bucket for (salt, visitor). Uniform + deterministic, not cryptographic;
+*  the shared pure hash keeps this module safe in ANY bundle (runtime + every island entry). */
+const pct = (s) => fnv1a32(s) % 1e4;
+/** Who is this? The router identity (folds in carried claims) when present; raw claims / the
+*  `og-vid` cookie (the router's `anonymousVisitor()` shape) otherwise; undefined = anonymous.
+*  The ONE rule: a flag read hashes on its `sub`, and the source is primed with it as `c.visitor`. */
+function visitor_of(c) {
+	if (c.visitor?.sub) return c.visitor;
+	const claims = c.request[CLAIMS];
+	if (claims?.sub) return claims;
+	const vid = c.cookies?.get("og-vid");
+	return vid ? {
+		sub: vid,
+		anonymous: true
+	} : c.visitor;
+}
+/** The sticky hash key. Anonymous → '' (weights degrade to the first variant there). */
+function visitor_id(c) {
+	return visitor_of(c)?.sub ?? "";
+}
+function carried(c, name) {
+	return c.request[CLAIMS]?.experiments?.[name];
+}
+let _source = null;
+let _override_gate = () => DEV;
+let _exposure = null;
+let _batch = {
+	max: 25,
+	ms: 2e3
+};
+let _queue = [];
+let _timer = null;
+/**
+* Configure flags for this server, once (hooks.server.ts / any server module). Everything is
+* optional — with no `decide()` at all, flags are native, sticky, and zero-JS.
+*
+*   decide({ source: openfeature(client), overrides: (c) => !!c.visitor?.qa, exposure: send });
+*/
+function decide(opts) {
+	if ("source" in opts) _source = opts.source ?? null;
+	if (opts.overrides) _override_gate = opts.overrides;
+	if ("exposure" in opts) _exposure = opts.exposure ?? null;
+	if (opts.batch) _batch = {
+		max: opts.batch.max ?? 25,
+		ms: opts.batch.ms ?? 2e3
+	};
+}
+function emit_exposure(e) {
+	if (!_exposure) return;
+	_queue.push(e);
+	if (_queue.length >= _batch.max) flush_exposures();
+	else if (!_timer) _timer = setTimeout(flush_exposures, _batch.ms);
+}
+/** Drain queued exposures to the sink. Called at each request's end (serverless-safe tail) and on
+*  the size/age caps. A sink failure is contained — a lost batch is never a request's problem. */
+function flush_exposures() {
+	if (_timer) clearTimeout(_timer);
+	_timer = null;
+	if (_queue.length === 0) return;
+	const batch = _queue;
+	_queue = [];
+	try {
+		_exposure?.(batch);
+	} catch {}
+}
+/** Every constructed flag self-registers here — the complete name list a source is asked for, and
+*  the set federation auto-carries. Import your flags (route modules do this at startup; on plain
+*  Kit, `import './flags'` in hooks.server.ts to prime the source from the first request). */
+const _registry = /* @__PURE__ */ new Map();
+/**
+* Resolve the source ONCE per request over every registered flag, caching decisions on the
+* Request so reads stay sync. Awaited by the flags plugin's `request` stage (flags/server.ts), above
+* the page / hole split. Idempotent; a no-op without a source. Never throws — a source failure
+* degrades every flag to its native rule, it does not take the request down.
+*/
+async function prime_flags(c) {
+	const req = c.request;
+	if (!_source || req[RESOLVED] !== void 0) return;
+	req[RESOLVED] = {};
+	if (_registry.size === 0) return;
+	try {
+		const out = await _source([..._registry.values()], {
+			...c,
+			visitor: visitor_of(c)
+		});
+		const map = {};
+		for (const q of _registry.values()) {
+			const raw = out?.[q.name];
+			if (raw === void 0) continue;
+			const norm = typeof raw === "boolean" ? { variant: raw ? "on" : "off" } : typeof raw === "string" ? { variant: raw } : raw;
+			if (norm && q.variants.includes(norm.variant)) map[q.name] = norm;
+		}
+		req[RESOLVED] = map;
+	} catch {
+		req[RESOLVED] = {};
+	}
+}
+function resolved_for(c, name) {
+	const map = c.request[RESOLVED];
+	if (map === void 0 && _source && !_unprimed_warned) {
+		_unprimed_warned = true;
+		console.warn("[ogygia] flags: `decide({ source })` is set but no request was primed — list `flags()` beside `ogygia()` in vite.config `plugins`.");
+	}
+	return map?.[name];
+}
+let _unprimed_warned = false;
+let _unstarted_warned = false;
+/** Record the decided variant as a request fact: federation carries the set as signed claims. */
+function record_assigned(c, name, variant) {
+	const facts = flags_app()?.facts(c.request);
+	if (facts) facts.assignments[name] = variant;
+}
+function override(c, name) {
+	if (!_override_gate(c)) return void 0;
+	for (const raw of c.url.searchParams.getAll("og-exp")) for (const pair of raw.split(",")) {
+		const [n, v] = pair.split(":");
+		if (n === name && v) return v;
+	}
+}
+const _layers = /* @__PURE__ */ new Map();
+function layer_member_for(group, v) {
+	const members = _layers.get(group);
+	if (!members || members.length === 0) return void 0;
+	const lanes = [...members].sort();
+	return lanes[pct(`layer:${group}:${v}`) % lanes.length];
+}
+function flag(name, shape, opts = {}) {
+	const is_record = shape !== null && typeof shape === "object";
+	const variants = is_record ? Object.keys(shape) : ["off", "on"];
+	const control = variants[0];
+	const weights = is_record ? shape : null;
+	const rollout = typeof shape === "number" ? shape : null;
+	const target = typeof shape === "function" ? shape : null;
+	_registry.set(name, {
+		name,
+		variants,
+		kind: is_record ? "variant" : "boolean"
+	});
+	if (opts.layer) {
+		const members = _layers.get(opts.layer) ?? [];
+		if (!members.includes(name)) members.push(name);
+		_layers.set(opts.layer, members);
+	}
+	const memo = /* @__PURE__ */ new WeakMap();
+	const compute = (c) => {
+		const o = override(c, name);
+		if (o && variants.includes(o)) return o;
+		const carried_v = carried(c, name);
+		if (carried_v && variants.includes(carried_v)) return carried_v;
+		const src = resolved_for(c, name);
+		if (src) return src.variant;
+		const v = visitor_id(c);
+		if (opts.layer && layer_member_for(opts.layer, v) !== name) return control;
+		if (target) {
+			const t = target(c);
+			if (t !== void 0) return t ? "on" : "off";
+		}
+		if (weights && v) {
+			const total = Object.values(weights).reduce((a, b) => a + (b > 0 ? b : 0), 0);
+			if (total > 0) {
+				const h = pct(`${name}:${v}`) / 1e4 * total;
+				let floor = 0;
+				for (const variant of variants) {
+					const share = weights[variant] > 0 ? weights[variant] : 0;
+					if (h >= floor && h < floor + share) return variant;
+					floor += share;
+				}
+			}
+		}
+		if (rollout && v) {
+			const share = rollout * 100;
+			if (pct(`${name}:${v}`) < share) return "on";
+		}
+		return control;
+	};
+	const bucket = (c) => {
+		const app = flags_app();
+		if (app) {
+			const facts = app.facts(c.request);
+			if (facts.perVisitor === null) facts.perVisitor = `flag:${name}`;
+		} else if (!BROWSER && !_unstarted_warned) {
+			_unstarted_warned = true;
+			console.warn("[ogygia] flags: a flag was read on the server but the flags plugin is not running — list `flags()` (from `@ogygia/flags/vite`) beside `ogygia()` in vite.config `plugins`. Until then flag reads are not reported to the request, and a stored page could keep one variant.");
+		}
+		const cached = memo.get(c.request);
+		if (cached !== void 0) return cached;
+		const variant = compute(c);
+		memo.set(c.request, variant);
+		record_assigned(c, name, variant);
+		emit_exposure({
+			name,
+			variant,
+			sub: c.visitor?.sub,
+			at: DEV ? 0 : now()
+		});
+		return variant;
+	};
+	const value = (c) => {
+		const raw = resolved_for(c, name)?.value;
+		if (raw !== void 0 && opts.value) {
+			const r = opts.value["~standard"].validate(raw);
+			if (r && typeof r.then !== "function") {
+				const res = r;
+				if (!res.issues) return res.value;
+			}
+		} else if (raw !== void 0 && !opts.value) return raw;
+		return opts.fallback;
+	};
+	const pick = (a, b) => {
+		if (b === void 0) {
+			const map = a;
+			return { __ogpick: (c) => map[bucket(c)] ?? map[control] };
+		}
+		return b[bucket(a)] ?? b[control];
+	};
+	const call = (c) => is_record ? bucket(c) : bucket(c) === "on";
+	Object.defineProperties(call, {
+		name: {
+			value: name,
+			enumerable: true
+		},
+		variants: {
+			value: variants,
+			enumerable: true
+		},
+		stamp: {
+			value: (c) => `${name}:${bucket(c)}`,
+			enumerable: true
+		},
+		value: {
+			value,
+			enumerable: true
+		},
+		pick: {
+			value: pick,
+			enumerable: true
+		}
+	});
+	return call;
+}
+/** `Date.now()` is unavailable in some sandboxes (workflow scripts); guard it so importing this
+*  module never throws there — exposure timestamps are 0 in that case (and in dev). */
+function now() {
+	try {
+		return Date.now();
+	} catch {
+		return 0;
+	}
+}
+export { decide, flag, flush_exposures, prime_flags };

package/dist/ofrep.d.ts

@@ -0,0 +1,15 @@
+import { CtxLike, FlagSource } from "./index.js";
+export interface OfrepOptions {
+  /** OFREP base URL (the adapter calls `<url>/ofrep/v1/evaluate/flags/bulk`). */
+  url: string;
+  /** Static headers (auth token, tenant) sent with every evaluation. */
+  headers?: Record<string, string>;
+  /** Build the OFREP evaluation context from the request (default: visitor `sub` →
+   *  `targetingKey` plus every own key of `c.visitor`). */
+  context?: (c: CtxLike) => Record<string, unknown>;
+  /** Per-request fetch (default global). */
+  fetch?: typeof fetch;
+  /** Abort the evaluation after N ms (default 800 — a flag service must not gate first byte). */
+  timeout?: number;
+}
+export declare function ofrep(opts: OfrepOptions): FlagSource;

package/dist/ofrep.js

@@ -0,0 +1,44 @@
+// src/ofrep.ts
+const TRAILING_SLASH_RE = /\/$/;
+function default_context(c) {
+	const sub = c.visitor?.sub;
+	return {
+		...c.visitor,
+		...sub ? { targetingKey: sub } : {}
+	};
+}
+function ofrep(opts) {
+	const ctx_of = opts.context ?? default_context;
+	const f = opts.fetch ?? fetch;
+	const endpoint = opts.url.replace(TRAILING_SLASH_RE, "") + "/ofrep/v1/evaluate/flags/bulk";
+	const timeout = opts.timeout ?? 800;
+	return async (queries, c) => {
+		const out = {};
+		try {
+			const res = await f(endpoint, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					...opts.headers
+				},
+				body: JSON.stringify({ context: ctx_of(c) }),
+				signal: AbortSignal.timeout(timeout)
+			});
+			if (!res.ok) return out;
+			const body = await res.json();
+			const want = new Map(queries.map((q) => [q.name, q]));
+			for (const f of body.flags ?? []) {
+				const q = want.get(f.key);
+				if (!q || f.errorCode) continue;
+				const variant = f.variant ?? (typeof f.value === "boolean" ? f.value ? "on" : "off" : void 0);
+				if (variant === void 0 || !q.variants.includes(variant)) continue;
+				out[f.key] = f.value !== void 0 && typeof f.value !== "boolean" ? {
+					variant,
+					value: f.value
+				} : variant;
+			}
+		} catch {}
+		return out;
+	};
+}
+export { ofrep };

package/dist/openfeature.d.ts

@@ -0,0 +1,23 @@
+import { CtxLike, FlagSource } from "./index.js";
+import { OfrepOptions, ofrep } from "./ofrep.js";
+/** The slice of the OpenFeature server `Client` we use — structural, so any SDK version fits. */
+export interface OpenFeatureClientLike {
+  getBooleanValue(flagKey: string, defaultValue: boolean, context?: EvaluationContextLike): Promise<boolean>;
+  getStringValue(flagKey: string, defaultValue: string, context?: EvaluationContextLike): Promise<string>;
+  /** Optional: variants that carry a config payload read via `.value(c)`. */
+  getObjectValue?<T>(flagKey: string, defaultValue: T, context?: EvaluationContextLike): Promise<T>;
+}
+export interface EvaluationContextLike {
+  targetingKey?: string;
+  [k: string]: unknown;
+}
+export interface OpenFeatureOptions {
+  /** Build the OpenFeature evaluation context from the request (default: visitor `sub` →
+   *  `targetingKey`, plus every own key of `c.visitor`). */
+  context?: (c: CtxLike) => EvaluationContextLike;
+  /** Also pull each flag's object value as the `.value(c)` payload (one extra eval per flag).
+   *  Off by default — most flags are variant-only. */
+  values?: boolean;
+}
+export declare function openfeature(client: OpenFeatureClientLike, opts?: OpenFeatureOptions): FlagSource;
+export { type OfrepOptions, ofrep };

package/dist/openfeature.js

@@ -0,0 +1,39 @@
+import { ofrep } from "./ofrep.js";
+// src/openfeature.ts
+function default_context(c) {
+	const sub = c.visitor?.sub;
+	return {
+		...c.visitor,
+		...sub ? { targetingKey: sub } : {}
+	};
+}
+function openfeature(client, opts = {}) {
+	const ctx_of = opts.context ?? default_context;
+	return async (queries, c) => {
+		const context = ctx_of(c);
+		const out = {};
+		await Promise.all(queries.map(async (q) => {
+			try {
+				if (q.kind === "boolean") {
+					const on = await client.getBooleanValue(q.name, false, context);
+					out[q.name] = on ? "on" : "off";
+				} else {
+					const variant = await client.getStringValue(q.name, q.variants[0], context);
+					out[q.name] = variant;
+				}
+				if (opts.values && client.getObjectValue) {
+					const value = await client.getObjectValue(q.name, void 0, context);
+					if (value !== void 0) {
+						const prev = out[q.name];
+						out[q.name] = {
+							variant: typeof prev === "string" ? prev : q.variants[0],
+							value
+						};
+					}
+				}
+			} catch {}
+		}));
+		return out;
+	};
+}
+export { ofrep, openfeature };

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { ServerPlugin } from "@ogygia/core/plugin";
+declare const server: ServerPlugin;
+export { server as default };

package/dist/server.js

@@ -0,0 +1,25 @@
+import { flush_exposures, prime_flags } from "./index.js";
+import { set_flags_app } from "./app.js";
+import { defineServer } from "@ogygia/core/plugin";
+// src/server.ts
+/**
+* The flags plugin's server realm (named by `flags()`).
+* `request`: prime the decision source once, above the page / hole split, so every read stays sync.
+* `done`: drain queued exposures at the request's end, always (the serverless-safe tail).
+*/
+const server = defineServer({
+	setup(app) {
+		set_flags_app(app);
+	},
+	async request({ event }) {
+		await prime_flags({
+			request: event.request,
+			url: event.url,
+			cookies: event.cookies
+		});
+	},
+	done() {
+		flush_exposures();
+	}
+});
+export { server as default };

package/dist/vite.d.ts

@@ -0,0 +1,2 @@
+import { OgygiaPlugin } from "@ogygia/core/vite";
+export declare function flags(): OgygiaPlugin;

package/dist/vite.js

@@ -0,0 +1,14 @@
+import { definePlugin } from "@ogygia/core/vite";
+// src/vite.ts
+/**
+* `flags()` — the flags plugin, listed beside `ogygia()` in vite.config `plugins`. Turns on the
+* per-request source priming and exposure flushing (its server realm); `flag()` itself works without
+* it (native, sticky decisions), but a `decide({ source, exposure })` needs it.
+*/
+function flags() {
+	return definePlugin({
+		name: "@ogygia/flags",
+		server: import.meta.resolve("./server.js")
+	});
+}
+export { flags };

package/package.json

@@ -1,7 +1,61 @@
 {
-	"name": "@ogygia/flags",
-	"version": "0.0.0",
-	"description": "Reserved for ogygia. The first release is on its way: https://ogygia.puruvj.dev",
-	"license": "MIT",
-	"repository": { "type": "git", "url": "git+https://github.com/ogygiajs/ogygia.git", "directory": "packages/flags" }
-}
+  "name": "@ogygia/flags",
+  "version": "0.11.0",
+  "description": "Feature flags and A/B tests for ogygia: one flag() primitive, decided server-side, zero JS",
+  "keywords": [
+    "ab-testing",
+    "feature-flags",
+    "ogygia",
+    "openfeature",
+    "sveltekit"
+  ],
+  "homepage": "https://ogygiajs.dev",
+  "license": "MIT",
+  "author": "Puru Vijayvargia <devpuruvj@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ogygiajs/ogygia.git",
+    "directory": "packages/flags"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./openfeature": {
+      "types": "./dist/openfeature.d.ts",
+      "default": "./dist/openfeature.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "esm-env": "^1.2.2"
+  },
+  "devDependencies": {
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "tsdown": "^0.23.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.12",
+    "@ogygia/core": "0.11.0",
+    "@ogygia/tooling": "0.0.0"
+  },
+  "peerDependencies": {
+    "@ogygia/core": "^0.11.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc -p . && tsc -p test && vitest run",
+    "test": "vitest run"
+  }
+}