better-supabase 0.12.0 → 0.13.0

package/dist/flags-C--SBMT9.js

@@ -0,0 +1,279 @@
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { t as DEFAULT_CLAIMS } from "./claims-Bp9My7XP.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-DwE32_gT.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-CJFDNAvL.d.ts

@@ -0,0 +1,246 @@
+import { T as ErrorMapper } from "./result-mijqfoJN.js";
+import { t as BlockTransport } from "./block-transport-DBPhgF3W.js";
+import { r as BlockTemporalOptions } from "./block-helpers-DyA5BAW4.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-sdk/index.d.ts

@@ -1,4 +1,4 @@
-import { a as FlagDefinition, g as FlagsProviderOptions, h as FlagsProvider, m as FlagValue, n as FlagContext, r as FlagContextOptions } from "../flags-6KK6Vqkr.js";
+import { a as FlagDefinition, g as FlagsProviderOptions, h as FlagsProvider, m as FlagValue, n as FlagContext, r as FlagContextOptions } from "../flags-CJFDNAvL.js";
 //#region src/flags-sdk/flags-sdk.d.ts
 /** One Flags SDK entity; Vercel Flags targets it as `<name>.id`. */
 interface FlagsSdkEntity {
@@ -31,8 +31,8 @@ interface FlagsSdkRequest {
   };
 }
 /**
- * Where a flag is managed, for Flags Explorer: a function of the key, or a
- * URL in which `{key}` is replaced by the key.
+ * 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. */
@@ -41,8 +41,8 @@ interface FlagsSdkOption {
   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.
+ * 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;
@@ -69,8 +69,8 @@ type BetterSupabaseAdapterOptions = ({
   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
+ * 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 {
@@ -83,10 +83,10 @@ 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.
+ * 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>>;
@@ -106,8 +106,8 @@ interface CreateIdentifyOptions extends FlagContextOptions {
   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.
+ * 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>;
 /**

package/dist/flags-sdk/index.js

@@ -1,5 +1,5 @@
-import { f as errorText } from "../block-helpers-DkVZNDrj.js";
-import { a as flagContext, n as createFlagsProvider, r as evaluateFlag } from "../flags-aUR7Rod6.js";
+import { f as errorText } from "../block-helpers-DwE32_gT.js";
+import { a as flagContext, n as createFlagsProvider, r as evaluateFlag } from "../flags-C--SBMT9.js";
 //#region src/flags-sdk/flags-sdk.ts
 function originOf(origin, key) {
 	return typeof origin === "function" ? origin(key) : origin?.replaceAll("{key}", encodeURIComponent(key));
@@ -20,17 +20,20 @@ function flagContextOf(entities) {
 		...Object.keys(contexts).length > 0 && { contexts }
 	};
 }
-/** Whether `value` fits a flag of `type`; an `object` flag holds any JSON object or list. */
+/**
+* Whether `value` fits a flag of `type`; an `object` flag holds any JSON object
+* or list.
+*/
 function fitsType(value, type) {
 	return type === "object" ? typeof value === "object" && value !== null : typeof value === type;
 }
 /**
-* The flag's value for a declaration with `defaultValue`, or `undefined`
-* for the fallback: a missing variant or an unknown type always falls back.
-* A `null` value is served to a declaration whose default is `null` or
-* unset. Otherwise a declaration without a default takes any value, one
-* with a `null` default a value of the flag's type, and any other default a
-* value of its own `typeof`.
+* The flag's value for a declaration with `defaultValue`, or `undefined` for
+* the fallback: a missing variant or an unknown type always falls back. A
+* `null` value is served to a declaration whose default is `null` or unset.
+* Otherwise a declaration without a default takes any value, one with a `null`
+* default a value of the flag's type, and any other default a value of its own
+* `typeof`.
 */
 async function valueOf(flag, defaultValue, context) {
 	if (!flag || flag.invalidType !== void 0) return;
@@ -45,10 +48,10 @@ const why = (flag) => flag === void 0 ? "it is missing" : flag.invalidType === v
 /**
 * 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.
+* 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.
 */
 function betterSupabaseAdapter(options) {
 	const provider = options.provider ?? createFlagsProvider(options);
@@ -95,8 +98,8 @@ function betterSupabaseAdapter(options) {
 	});
 }
 /**
-* An `identify` for `flag()` declarations, built on `flagContext()`. Wrap it
-* in the Flags SDK's `dedupe` so it runs once per request.
+* An `identify` for `flag()` declarations, built on `flagContext()`. Wrap it in
+* the Flags SDK's `dedupe` so it runs once per request.
 */
 function createIdentify(options) {
 	return async (request) => {