better-supabase 0.8.0 → 0.9.0

package/dist/flags-D_D1jAHB.d.ts

@@ -0,0 +1,230 @@
+import { w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { t as BlockTransport } from "./block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "./block-helpers-C86hPEjI.js";
+//#region src/blocks/flags/flags.d.ts
+type FlagType = "boolean" | "string" | "number" | "object";
+type FlagValue = boolean | string | number | null | FlagValue[] | {
+  [key: string]: FlagValue;
+};
+/** A targeting rule: every list that is set must contain the caller's value. */
+interface FlagRule {
+  readonly variant: string;
+  readonly tenants?: readonly string[];
+  readonly users?: readonly string[];
+  /** Entitlement lookup keys; one match is enough. */
+  readonly plans?: readonly string[];
+  readonly roles?: readonly string[];
+  /** Custom contexts by name, such as `{ brand: ["acme"] }`; every one must match. */
+  readonly contexts?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * A variant for one tenant, one user or one custom context value. A user
+ * override beats a tenant one, and a tenant one beats a context one; among
+ * context overrides, the first in the list wins (`flag_definitions()` lists
+ * them in the declared order of `options.contexts`).
+ */
+interface FlagOverride {
+  readonly organizationId: string | undefined;
+  readonly userId: string | undefined;
+  /** The custom context, such as `brand`, with `contextKey` its value. */
+  readonly context?: string | undefined;
+  readonly contextKey?: string | undefined;
+  readonly variant: string;
+}
+/** A row of the `flags` table with its overrides (`flag_definitions()`). */
+interface FlagDefinition {
+  readonly key: string;
+  /** `"boolean"` when the row's type is unknown; `invalidType` then holds it. */
+  readonly type: FlagType;
+  /**
+   * The row's type when it isn't one of `FlagType`. Such a flag is never
+   * served: the adapters fall back and the provider reports `PARSE_ERROR`.
+   */
+  readonly invalidType?: string;
+  readonly description?: string;
+  readonly variants: Readonly<Record<string, FlagValue>>;
+  readonly defaultVariant: string;
+  readonly enabled: boolean;
+  /** An archived flag serves its default variant and is hidden from Flags Explorer. */
+  readonly archived?: boolean;
+  readonly rules: readonly FlagRule[];
+  /** 0 to 100, in steps of 0.01. */
+  readonly rolloutPercentage: number;
+  readonly rolloutVariant: string | undefined;
+  readonly overrides: readonly FlagOverride[];
+  /** When the flag last changed, as an ISO 8601 string. */
+  readonly updatedAt?: string;
+  /** The extra columns (`blocks.flags.options.extraColumns`), when the flag has any. */
+  readonly fields?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The OpenFeature evaluation context the provider reads. `targetingKey` is
+ * the user id; without one, the rollout buckets by `tenant`.
+ */
+interface FlagContext {
+  readonly targetingKey?: string;
+  readonly tenant?: string;
+  readonly plans?: readonly string[];
+  readonly role?: string;
+  /** Every role the caller holds in the tenant; a `roles` rule matches any of them. */
+  readonly roles?: readonly string[];
+  /**
+   * Custom context values by name, such as `{ brand: "acme" }`. Unlike
+   * `flag_evaluation()`, the provider never reads them from the tenant.
+   */
+  readonly contexts?: Readonly<Record<string, string>>;
+  readonly [attribute: string]: unknown;
+}
+/**
+ * What `flagContext()` returns; an OpenFeature `EvaluationContext`. It is a
+ * type alias because an interface has no implicit index signature.
+ */
+type RequestFlagContext = {
+  targetingKey?: string;
+  tenant?: string;
+  plans?: string[];
+  role?: string;
+  roles?: string[];
+  contexts?: Record<string, string>;
+};
+type FlagReason = "DISABLED" | "TARGETING_MATCH" | "SPLIT" | "DEFAULT" | "ERROR";
+type FlagErrorCode = "FLAG_NOT_FOUND" | "TYPE_MISMATCH" | "PARSE_ERROR" | "PROVIDER_NOT_READY" | "GENERAL";
+/**
+ * The shape of an OpenFeature `ResolutionDetails`. `Code` is the type of
+ * `errorCode`: OpenFeature's `ErrorCode` when `errorCodes: ErrorCode` is
+ * passed to the provider, the matching string literals otherwise.
+ */
+interface FlagResolution<T, Code extends string = FlagErrorCode> {
+  readonly value: T;
+  readonly variant?: string;
+  readonly reason: FlagReason;
+  readonly errorCode?: Code;
+  readonly errorMessage?: string;
+}
+/** The shape of an OpenFeature `EvaluationDetails`. */
+interface FlagDetails<T, Code extends string = FlagErrorCode> extends FlagResolution<T, Code> {
+  readonly flagKey: string;
+  readonly flagMetadata: Readonly<Record<string, string | number | boolean>>;
+}
+/**
+ * The rollout bucket of `target` for `flag`, 0 to 9999: the first 32 bits
+ * of SHA-256(`flag.target`) modulo 10000. `better_supabase.flag_bucket()`
+ * computes the same number, so SQL and TypeScript agree on who is in.
+ */
+declare function flagBucket(flag: string, target: string): Promise<number>;
+/** The result of `evaluateFlag()`, which never fails. */
+interface FlagEvaluation {
+  /** The variant's value; `null` when `found` is false. */
+  readonly value: FlagValue;
+  readonly variant: string;
+  readonly reason: FlagReason;
+  /** Whether `variants` has the chosen variant, so a `null` value is real. */
+  readonly found: boolean;
+}
+/** Evaluates one flag as `better_supabase.flag_evaluation()` does. */
+declare function evaluateFlag(flag: FlagDefinition, context?: FlagContext): Promise<FlagEvaluation>;
+/** Parses the rows of `flag_definitions()`. */
+declare function flagDefinitionsOf(value: unknown): readonly FlagDefinition[];
+interface FlagsProviderOptions<Code extends string = FlagErrorCode> extends BlockTemporalOptions {
+  /**
+   * A service-role transport: `flag_definitions()` is granted to
+   * `service_role` only, as it lists every override.
+   */
+  readonly transport?: BlockTransport;
+  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. Default `better_supabase`. */
+  readonly schema?: string;
+  /** Error mappers that run before the built-in ones. */
+  readonly mappers?: readonly ErrorMapper[];
+  /** How long the definitions are cached, in milliseconds. Default 30000. */
+  readonly ttl?: number;
+  /** Fixed definitions instead of a transport, for tests and static flags. */
+  readonly definitions?: readonly FlagDefinition[];
+  /**
+   * OpenFeature's `ErrorCode` enum (from `@openfeature/core` or
+   * `@openfeature/server-sdk`), so the provider's types match `Provider`.
+   * A map without `PARSE_ERROR` reports an unknown flag type as `GENERAL`.
+   */
+  readonly errorCodes?: Readonly<Record<Exclude<FlagErrorCode, "PARSE_ERROR">, Code> & Partial<Record<"PARSE_ERROR", Code>>>;
+  readonly now?: () => number;
+}
+/**
+ * The shape of an OpenFeature server `Provider`. Pass it to
+ * `OpenFeature.setProviderAndWait()`; this package never imports OpenFeature.
+ */
+interface FlagsProvider<Code extends string = FlagErrorCode> {
+  readonly metadata: {
+    readonly name: string;
+  };
+  readonly runsOn: "server";
+  initialize(context?: FlagContext): Promise<void>;
+  resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: FlagContext): Promise<FlagResolution<boolean, Code>>;
+  resolveStringEvaluation(flagKey: string, defaultValue: string, context: FlagContext): Promise<FlagResolution<string, Code>>;
+  resolveNumberEvaluation(flagKey: string, defaultValue: number, context: FlagContext): Promise<FlagResolution<number, Code>>;
+  resolveObjectEvaluation<T extends FlagValue>(flagKey: string, defaultValue: T, context: FlagContext): Promise<FlagResolution<T, Code>>;
+  /**
+   * Every definition, from the same cache as the evaluations. It rejects when
+   * the definitions fail to load.
+   */
+  definitions(): Promise<readonly FlagDefinition[]>;
+  /** Drops the cache, so the next evaluation reloads the definitions. */
+  refresh(): void;
+}
+/** Feature flags from the `flags` module, as an OpenFeature provider. */
+declare function createFlagsProvider<Code extends string = FlagErrorCode>(options: FlagsProviderOptions<Code>): FlagsProvider<Code>;
+/**
+ * The four `get*Details` methods that the OpenFeature server `Client` and
+ * the `FlagClient` of `@supabase-labs/middleware-openfeature` share.
+ */
+interface FlagClient<Code extends string = FlagErrorCode> {
+  getBooleanDetails(flagKey: string, defaultValue: boolean, context?: FlagContext): Promise<FlagDetails<boolean, Code>>;
+  getStringDetails(flagKey: string, defaultValue: string, context?: FlagContext): Promise<FlagDetails<string, Code>>;
+  getNumberDetails(flagKey: string, defaultValue: number, context?: FlagContext): Promise<FlagDetails<number, Code>>;
+  getObjectDetails<T extends FlagValue>(flagKey: string, defaultValue: T, context?: FlagContext): Promise<FlagDetails<T, Code>>;
+}
+/**
+ * A flag client without the OpenFeature SDK: `withOpenFeature({ client })`
+ * from `@supabase-labs/middleware-openfeature` accepts it.
+ */
+declare function createFlagClient<Code extends string = FlagErrorCode>(source: FlagsProvider<Code> | FlagsProviderOptions<Code>): FlagClient<Code>;
+interface FlagContextSource {
+  /** `ctx.jwtClaims` from `withBetterSupabase`, or verified claims. */
+  readonly jwtClaims?: Readonly<Record<string, unknown>> | null | undefined;
+  /** The active tenant; default the `tenant_id` claim. */
+  readonly tenant?: string | null | undefined;
+  /**
+   * Custom context values the request carries, such as the brand from the
+   * host. They win over `options.contextClaims`; `null` leaves one out.
+   */
+  readonly contexts?: Readonly<Record<string, string | null | undefined>>;
+}
+interface FlagContextOptions {
+  /** `config.claims.tenant`, default `tenant_id`. */
+  readonly tenantClaim?: string;
+  /** `config.claims.features`, default `features`. */
+  readonly featuresClaim?: string;
+  /** The claim the memberships hook writes, default `memberships`. */
+  readonly membershipsClaim?: string;
+  /**
+   * The scope of tenant memberships when the claim is a list of entries, as
+   * an authorization provider's hook may write it (`{ scope, id, roles }`). Without it, the entry
+   * for the tenant id that has no `within` (a root scope) is read.
+   */
+  readonly membershipScope?: string;
+  /** Reads the caller's roles in `tenant` from claims of another shape. */
+  readonly roles?: (claims: Readonly<Record<string, unknown>>, tenant: string) => string | readonly string[] | undefined;
+  /**
+   * Custom contexts read from claims: a context name to the claim that holds
+   * it, such as `{ brand: "brand_id" }`. A claim is read from the top level,
+   * then from `app_metadata`.
+   */
+  readonly contextClaims?: Readonly<Record<string, string>>;
+}
+/**
+ * The evaluation context of a request: the user id as `targetingKey`, the
+ * tenant, its plan features (`features` claim) and the caller's roles in it
+ * (`memberships` claim, in the `tenant` module's or the list shape, or
+ * `options.roles`). Pass it as `context` to `withOpenFeature`.
+ */
+declare function flagContext(source: FlagContextSource, options?: FlagContextOptions): RequestFlagContext;
+//#endregion
+export { flagDefinitionsOf as C, flagContext as S, RequestFlagContext as _, FlagDefinition as a, evaluateFlag as b, FlagEvaluation as c, FlagResolution as d, FlagRule as f, FlagsProviderOptions as g, FlagsProvider as h, FlagContextSource as i, FlagOverride as l, FlagValue as m, FlagContext as n, FlagDetails as o, FlagType as p, FlagContextOptions as r, FlagErrorCode as s, FlagClient as t, FlagReason as u, createFlagClient as v, flagBucket as x, createFlagsProvider as y };

package/dist/flags-XAOsdNAc.js

@@ -0,0 +1,279 @@
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { t as DEFAULT_CLAIMS } from "./claims-PqzCxaTD.js";
+import { C as optionalText, F as stringsOf, I as textOf, f as errorText, k as recordsOf, n as applyTemporal, o as blockCall } from "./block-helpers-CfG_MvDR.js";
+//#region src/blocks/flags/flags.ts
+const BUCKETS = 1e4;
+/**
+* The rollout bucket of `target` for `flag`, 0 to 9999: the first 32 bits
+* of SHA-256(`flag.target`) modulo 10000. `better_supabase.flag_bucket()`
+* computes the same number, so SQL and TypeScript agree on who is in.
+*/
+async function flagBucket(flag, target) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${flag}.${target}`));
+	return new DataView(digest).getUint32(0) % BUCKETS;
+}
+const contains = (list, value) => list === void 0 || value !== void 0 && list.includes(value);
+const anyIn = (list, values) => list === void 0 || values.some((value) => list.includes(value));
+function ruleMatches(rule, context) {
+	return contains(rule.tenants, context.tenant) && contains(rule.users, context.targetingKey) && anyIn(rule.roles, [...context.role === void 0 ? [] : [context.role], ...context.roles ?? []]) && (rule.plans === void 0 || rule.plans.some((plan) => context.plans?.includes(plan) === true)) && (rule.contexts === void 0 || Object.entries(rule.contexts).every(([name, keys]) => contains(keys, context.contexts?.[name])));
+}
+async function chooseVariant(flag, context) {
+	if (!flag.enabled || flag.archived === true) return {
+		variant: flag.defaultVariant,
+		reason: "DISABLED"
+	};
+	let chosen = (flag.overrides.find((entry) => entry.userId !== void 0 && entry.userId === context.targetingKey) ?? flag.overrides.find((entry) => entry.organizationId !== void 0 && entry.organizationId === context.tenant) ?? flag.overrides.find((entry) => entry.context !== void 0 && entry.contextKey !== void 0 && entry.contextKey === context.contexts?.[entry.context]))?.variant;
+	let reason = chosen === void 0 ? "DEFAULT" : "TARGETING_MATCH";
+	if (chosen === void 0) {
+		const rule = flag.rules.find((entry) => ruleMatches(entry, context));
+		if (rule) {
+			chosen = rule.variant;
+			reason = "TARGETING_MATCH";
+		}
+	}
+	const target = context.targetingKey ?? context.tenant;
+	if (chosen === void 0 && flag.rolloutVariant !== void 0 && target !== void 0 && await flagBucket(flag.key, target) < flag.rolloutPercentage * 100) {
+		chosen = flag.rolloutVariant;
+		reason = "SPLIT";
+	}
+	if (chosen === void 0 || !Object.hasOwn(flag.variants, chosen)) return {
+		variant: flag.defaultVariant,
+		reason: "DEFAULT"
+	};
+	return {
+		variant: chosen,
+		reason
+	};
+}
+/** Evaluates one flag as `better_supabase.flag_evaluation()` does. */
+async function evaluateFlag(flag, context = {}) {
+	const { variant, reason } = await chooseVariant(flag, context);
+	const found = Object.hasOwn(flag.variants, variant);
+	return {
+		value: found ? flag.variants[variant] ?? null : null,
+		variant,
+		reason,
+		found
+	};
+}
+const FLAG_TYPES = /* @__PURE__ */ new Set([
+	"boolean",
+	"string",
+	"number",
+	"object"
+]);
+const flagTypeOf = (value) => {
+	const text = textOf(value);
+	if (value === void 0 || value === null || FLAG_TYPES.has(text)) return { type: FLAG_TYPES.has(text) ? text : "boolean" };
+	return {
+		type: "boolean",
+		invalidType: text
+	};
+};
+function ruleOf(value) {
+	if (!isRecord(value) || typeof value["variant"] !== "string") return;
+	const list = (key) => Array.isArray(value[key]) ? stringsOf(value[key]) : void 0;
+	const tenants = list("tenants");
+	const users = list("users");
+	const plans = list("plans");
+	const roles = list("roles");
+	const raw = value["contexts"];
+	const contexts = isRecord(raw) ? Object.fromEntries(Object.entries(raw).map(([name, keys]) => [name, Array.isArray(keys) ? stringsOf(keys) : []])) : void 0;
+	return {
+		variant: value["variant"],
+		...tenants && { tenants },
+		...users && { users },
+		...plans && { plans },
+		...roles && { roles },
+		...contexts && { contexts }
+	};
+}
+/** Parses the rows of `flag_definitions()`. */
+function flagDefinitionsOf(value) {
+	return recordsOf(value, "flag_definitions").map((row) => ({
+		key: textOf(row["key"]),
+		...flagTypeOf(row["type"]),
+		variants: isRecord(row["variants"]) ? row["variants"] : {},
+		defaultVariant: optionalText(row["default_variant"]) ?? "",
+		...optionalText(row["description"]) !== void 0 && { description: textOf(row["description"]) },
+		enabled: row["enabled"] !== false,
+		...row["archived"] === true && { archived: true },
+		rules: (Array.isArray(row["rules"]) ? row["rules"] : []).flatMap((rule) => {
+			const parsed = ruleOf(rule);
+			return parsed ? [parsed] : [];
+		}),
+		rolloutPercentage: Number(row["rollout_percentage"] ?? 0),
+		rolloutVariant: optionalText(row["rollout_variant"]),
+		overrides: recordsOf(row["overrides"] ?? [], "flag_definitions").map(overrideOf),
+		...optionalText(row["updated_at"]) !== void 0 && { updatedAt: textOf(row["updated_at"]) },
+		...isRecord(row["fields"]) ? { fields: row["fields"] } : {}
+	}));
+}
+function overrideOf(entry) {
+	const context = optionalText(entry["context"]);
+	const contextKey = optionalText(entry["context_key"]);
+	return {
+		organizationId: optionalText(entry["organization_id"]),
+		userId: optionalText(entry["user_id"]),
+		...context !== void 0 && { context },
+		...contextKey !== void 0 && { contextKey },
+		variant: textOf(entry["variant"])
+	};
+}
+const DEFAULT_CODES = {
+	FLAG_NOT_FOUND: "FLAG_NOT_FOUND",
+	TYPE_MISMATCH: "TYPE_MISMATCH",
+	PARSE_ERROR: "PARSE_ERROR",
+	PROVIDER_NOT_READY: "PROVIDER_NOT_READY",
+	GENERAL: "GENERAL"
+};
+const isBoolean = (value) => typeof value === "boolean";
+const isString = (value) => typeof value === "string";
+const isNumber = (value) => typeof value === "number";
+/** Feature flags from the `flags` module, as an OpenFeature provider. */
+function createFlagsProvider(options) {
+	applyTemporal(options);
+	const { transport, definitions } = options;
+	const call = transport === void 0 ? void 0 : blockCall(transport, options.schema ?? "better_supabase", options.mappers);
+	const fetchFlags = definitions ? () => Promise.resolve(definitions) : call ? () => call("flag_definitions", {}, flagDefinitionsOf).orThrow() : void 0;
+	if (!fetchFlags) throw new TypeError("createFlagsProvider needs a transport or definitions");
+	const ttl = options.ttl ?? 3e4;
+	const now = options.now ?? Date.now;
+	const codes = options.errorCodes ?? DEFAULT_CODES;
+	let cache;
+	const load = () => {
+		if (cache && now() - cache.at < ttl) return cache.flags;
+		const flags = fetchFlags().then((list) => new Map(list.map((flag) => [flag.key, flag])));
+		const entry = {
+			at: now(),
+			flags
+		};
+		cache = entry;
+		flags.catch(() => {
+			if (cache === entry) cache = void 0;
+		});
+		return flags;
+	};
+	async function resolve(flagKey, defaultValue, context, check) {
+		let flags;
+		try {
+			flags = await load();
+		} catch (error) {
+			return {
+				value: defaultValue,
+				reason: "ERROR",
+				errorCode: codes.GENERAL,
+				errorMessage: errorText(error)
+			};
+		}
+		const flag = flags.get(flagKey);
+		if (!flag) return {
+			value: defaultValue,
+			reason: "ERROR",
+			errorCode: codes.FLAG_NOT_FOUND,
+			errorMessage: `Flag "${flagKey}" is not defined`
+		};
+		if (flag.invalidType !== void 0) return {
+			value: defaultValue,
+			reason: "ERROR",
+			errorCode: codes.PARSE_ERROR ?? codes.GENERAL,
+			errorMessage: `Flag "${flagKey}" has the unknown type "${flag.invalidType}"`
+		};
+		const result = await evaluateFlag(flag, context);
+		if (!check(result.value)) return {
+			value: defaultValue,
+			reason: "ERROR",
+			errorCode: codes.TYPE_MISMATCH,
+			errorMessage: `Flag "${flagKey}" is a ${flag.type} flag`
+		};
+		return {
+			value: result.value,
+			variant: result.variant,
+			reason: result.reason
+		};
+	}
+	return {
+		metadata: { name: "better-supabase" },
+		runsOn: "server",
+		async initialize() {
+			await load();
+		},
+		resolveBooleanEvaluation: (flagKey, defaultValue, context) => resolve(flagKey, defaultValue, context, isBoolean),
+		resolveStringEvaluation: (flagKey, defaultValue, context) => resolve(flagKey, defaultValue, context, isString),
+		resolveNumberEvaluation: (flagKey, defaultValue, context) => resolve(flagKey, defaultValue, context, isNumber),
+		resolveObjectEvaluation: (flagKey, defaultValue, context) => resolve(flagKey, defaultValue, context, (value) => typeof value === "object" && value !== null),
+		definitions: async () => [...(await load()).values()],
+		refresh() {
+			cache = void 0;
+		}
+	};
+}
+const details = async (flagKey, resolution) => ({
+	flagKey,
+	flagMetadata: {},
+	...await resolution
+});
+/**
+* A flag client without the OpenFeature SDK: `withOpenFeature({ client })`
+* from `@supabase-labs/middleware-openfeature` accepts it.
+*/
+function createFlagClient(source) {
+	const provider = "resolveBooleanEvaluation" in source ? source : createFlagsProvider(source);
+	return {
+		getBooleanDetails: (flagKey, defaultValue, context = {}) => details(flagKey, provider.resolveBooleanEvaluation(flagKey, defaultValue, context)),
+		getStringDetails: (flagKey, defaultValue, context = {}) => details(flagKey, provider.resolveStringEvaluation(flagKey, defaultValue, context)),
+		getNumberDetails: (flagKey, defaultValue, context = {}) => details(flagKey, provider.resolveNumberEvaluation(flagKey, defaultValue, context)),
+		getObjectDetails: (flagKey, defaultValue, context = {}) => details(flagKey, provider.resolveObjectEvaluation(flagKey, defaultValue, context))
+	};
+}
+/**
+* The caller's roles in `tenant` from the memberships claim: an object of
+* tenant id to role (the `tenant` module's hook), or a list of
+* `{ scope, id, role | roles }` entries (an authorization provider's hook).
+*/
+function membershipRoles(memberships, tenant, scope) {
+	if (isRecord(memberships)) {
+		const role = optionalText(memberships[tenant]);
+		return role === void 0 ? [] : [role];
+	}
+	if (!Array.isArray(memberships)) return [];
+	const entry = memberships.find((item) => isRecord(item) && optionalText(item["id"]) === tenant && (scope === void 0 ? item["within"] === void 0 : optionalText(item["scope"]) === scope));
+	if (!entry) return [];
+	const role = optionalText(entry["role"]);
+	return [...role === void 0 ? [] : [role], ...stringsOf(entry["roles"])];
+}
+/**
+* The evaluation context of a request: the user id as `targetingKey`, the
+* tenant, its plan features (`features` claim) and the caller's roles in it
+* (`memberships` claim, in the `tenant` module's or the list shape, or
+* `options.roles`). Pass it as `context` to `withOpenFeature`.
+*/
+function flagContext(source, options = {}) {
+	const claims = source.jwtClaims ?? {};
+	const appMetadata = isRecord(claims["app_metadata"]) ? claims["app_metadata"] : {};
+	const tenantClaim = options.tenantClaim ?? DEFAULT_CLAIMS.tenant;
+	const tenant = source.tenant ?? optionalText(claims[tenantClaim]) ?? optionalText(appMetadata[tenantClaim]);
+	const sub = optionalText(claims["sub"]);
+	const features = claims[options.featuresClaim ?? DEFAULT_CLAIMS.features];
+	const memberships = claims[options.membershipsClaim ?? DEFAULT_CLAIMS.memberships];
+	const plans = tenant !== void 0 && isRecord(features) && Array.isArray(features[tenant]) ? [...stringsOf(features[tenant])] : void 0;
+	const resolved = tenant === void 0 ? void 0 : options.roles ? options.roles(claims, tenant) : membershipRoles(memberships, tenant, options.membershipScope);
+	const roles = resolved === void 0 ? [] : typeof resolved === "string" ? [resolved] : [...resolved];
+	const contexts = /* @__PURE__ */ new Map();
+	for (const [name, claim] of Object.entries(options.contextClaims ?? {})) {
+		const value = optionalText(claims[claim]) ?? optionalText(appMetadata[claim]);
+		if (value !== void 0) contexts.set(name, value);
+	}
+	for (const [name, value] of Object.entries(source.contexts ?? {})) if (typeof value === "string") contexts.set(name, value);
+	else contexts.delete(name);
+	return {
+		...sub !== void 0 && { targetingKey: sub },
+		...tenant !== void 0 && { tenant },
+		...plans !== void 0 && { plans },
+		...roles.length > 0 && { role: roles[0] },
+		...roles.length > 1 && { roles },
+		...contexts.size > 0 && { contexts: Object.fromEntries(contexts) }
+	};
+}
+//#endregion
+export { flagContext as a, flagBucket as i, createFlagsProvider as n, flagDefinitionsOf as o, evaluateFlag as r, createFlagClient as t };

package/dist/flags-sdk/index.d.ts

@@ -0,0 +1,143 @@
+import { a as FlagDefinition, g as FlagsProviderOptions, h as FlagsProvider, m as FlagValue, n as FlagContext, r as FlagContextOptions } from "../flags-D_D1jAHB.js";
+//#region src/flags-sdk/flags-sdk.d.ts
+/** One Flags SDK entity; Vercel Flags targets it as `<name>.id`. */
+interface FlagsSdkEntity {
+  readonly id: string;
+}
+/** The tenant, with the plan features and roles that rules match. */
+interface FlagsSdkOrganization extends FlagsSdkEntity {
+  readonly plans?: readonly string[];
+  readonly roles?: readonly string[];
+}
+/**
+ * What `identify` returns: the user, the tenant as `organization`, and each
+ * custom context, such as `brand`, as an entity of its own. The same shape
+ * works for `vercelAdapter`, so one `identify` serves both adapters.
+ */
+interface FlagsSdkEntities {
+  readonly user?: FlagsSdkEntity;
+  readonly organization?: FlagsSdkOrganization;
+  readonly [context: string]: FlagsSdkEntity | FlagsSdkOrganization | undefined;
+}
+/** The part of the Flags SDK request that `identify` receives. */
+interface FlagsSdkRequest {
+  readonly headers: {
+    get(name: string): string | null;
+  };
+  readonly cookies: {
+    get(name: string): {
+      readonly value: string;
+    } | undefined;
+  };
+}
+/**
+ * Where a flag is managed, for Flags Explorer: a function of the key, or a
+ * URL in which `{key}` is replaced by the key.
+ */
+type FlagsSdkOrigin = string | ((key: string) => string | undefined);
+/** A Flags SDK option: a variant's value, labelled with its name. */
+interface FlagsSdkOption {
+  value: FlagValue;
+  label: string;
+}
+/**
+ * The shape of a Flags SDK `Adapter` (`flags` 4.2 or later). This package
+ * never imports `flags`; a type test checks this shape against the real one.
+ */
+interface FlagsSdkAdapter<V, E = FlagsSdkEntities> {
+  readonly adapterId: symbol;
+  readonly origin?: (key: string) => string | undefined;
+  decide(params: {
+    readonly key: string;
+    readonly entities?: E;
+    readonly defaultValue?: unknown;
+  }): Promise<V>;
+  bulkDecide(params: {
+    readonly flags: readonly {
+      readonly key: string;
+      readonly defaultValue?: unknown;
+    }[];
+    readonly entities?: E;
+  }): Promise<Record<string, V>>;
+}
+type BetterSupabaseAdapterOptions = ({
+  readonly provider: FlagsProvider<string>;
+} | (FlagsProviderOptions & {
+  readonly provider?: never;
+})) & {
+  /** Where each flag is managed, such as the app's admin page. */
+  readonly origin?: FlagsSdkOrigin;
+};
+/**
+ * What `betterSupabaseAdapter()` returns. Pass it as `adapter` by reference
+ * or call it; every adapter it makes shares one definitions cache and one
+ * `adapterId`, so `evaluate()` decides them in one `bulkDecide`.
+ */
+interface BetterSupabaseAdapterFactory {
+  <V = FlagValue>(): FlagsSdkAdapter<V>;
+  readonly provider: FlagsProvider<string>;
+  readonly origin?: FlagsSdkOrigin;
+}
+/** Maps Flags SDK entities to the provider's evaluation context. */
+export declare function flagContextOf(entities?: FlagsSdkEntities): FlagContext;
+/**
+ * A Flags SDK adapter over the `flags` block. It evaluates rules, overrides,
+ * custom contexts and rollouts like `flag_evaluation()`, from definitions it
+ * caches for `ttl`. A flag that is missing, has an unknown type, has
+ * another type than the declaration or fails to load gets the declaration's
+ * `defaultValue`; without one, `decide` throws. A variant whose value is
+ * `null` is served to a declaration whose `defaultValue` is `null` or unset.
+ */
+export declare function betterSupabaseAdapter(options: BetterSupabaseAdapterOptions): BetterSupabaseAdapterFactory;
+type Claims = Readonly<Record<string, unknown>>;
+type MaybePromise<T> = T | Promise<T>;
+interface CreateIdentifyOptions extends FlagContextOptions {
+  /**
+   * The request's verified JWT claims, such as from `getClaims()`. Read them
+   * locally; `identify` runs for every flag and never calls the Auth server.
+   */
+  readonly claims: (request: FlagsSdkRequest) => MaybePromise<Claims | null | undefined>;
+  /** The active tenant when the claims don't carry it, such as from a cookie. */
+  readonly tenant?: (request: FlagsSdkRequest, claims: Claims | null | undefined) => MaybePromise<string | null | undefined>;
+  /**
+   * Custom context values, such as the brand from the host. They win over
+   * `contextClaims`; `null` leaves one out.
+   */
+  readonly contexts?: (request: FlagsSdkRequest, claims: Claims | null | undefined) => MaybePromise<Readonly<Record<string, string | null | undefined>> | undefined>;
+}
+/**
+ * An `identify` for `flag()` declarations, built on `flagContext()`. Wrap it
+ * in the Flags SDK's `dedupe` so it runs once per request.
+ */
+export declare function createIdentify(options: CreateIdentifyOptions): (request: FlagsSdkRequest) => Promise<FlagsSdkEntities>;
+/**
+ * A flag's variants as Flags SDK `options`, labelled by variant name. A
+ * precomputed flag needs them to list its permutations.
+ */
+export declare function flagOptions(definition: Pick<FlagDefinition, "variants">): FlagsSdkOption[];
+/** A flag as Flags Explorer describes it. */
+interface FlagsSdkDefinition {
+  options: FlagsSdkOption[];
+  description?: string;
+  origin?: string;
+  updatedAt?: number;
+}
+/** The Flags SDK's `ProviderData`, for `.well-known/vercel/flags`. */
+interface FlagsSdkProviderData {
+  definitions: Record<string, FlagsSdkDefinition>;
+  hints: {
+    key: string;
+    text: string;
+  }[];
+}
+/**
+ * Flags Explorer data for every flag that isn't archived. Pass the adapter
+ * factory or `{ provider, origin }`, and combine the result with other
+ * providers' data through `mergeProviderData`. A failed load becomes a hint.
+ */
+export declare function getProviderData(options: {
+  readonly provider: FlagsProvider<string>;
+  readonly origin?: FlagsSdkOrigin;
+}): Promise<FlagsSdkProviderData>;
+//#endregion
+export type { BetterSupabaseAdapterFactory, BetterSupabaseAdapterOptions, CreateIdentifyOptions, FlagsSdkAdapter, FlagsSdkDefinition, FlagsSdkEntities, FlagsSdkEntity, FlagsSdkOption, FlagsSdkOrganization, FlagsSdkOrigin, FlagsSdkProviderData, FlagsSdkRequest };