better-supabase 0.13.0 → 0.14.0

package/dist/filter-evaluate-C3i2bGfk.d.ts

@@ -0,0 +1,37 @@
+import { h as FilterQuery, l as FilterFieldType, r as FilterClock } from "./filter-query-o3b_GuyC.js";
+//#region src/list/filter-evaluate.d.ts
+/**
+ * A field a filter tree can test on a plain record. `FilterFieldInfo` from a
+ * list definition fits; the rules block builds these from its field catalog.
+ */
+interface FilterRecordField {
+  readonly id: string;
+  readonly type: FilterFieldType;
+  /** The record key the value is read from, dotted for a nested value. */
+  readonly column: string;
+  readonly columnMeta: {
+    /**
+     * The Postgres type: `date`, `timestamp` and `timestamptz` pick how dates
+     * compare.
+     */
+    readonly type: string;
+    readonly nullable: boolean;
+  };
+}
+/**
+ * The outcome of a tree on one record. `results` holds every rule and group
+ * that took part, by node id: `null` when a comparison met a missing value,
+ * which SQL treats as unknown and a match treats as false.
+ */
+interface FilterEvaluation {
+  readonly matched: boolean;
+  readonly results: Readonly<Record<string, boolean | null>>;
+}
+/**
+ * Tests a checked filter tree on one record, with the same operators and null
+ * handling as `filterWhere` compiles to SQL. Unfinished rules, unknown fields
+ * and empty groups take no part, and a tree with nothing left matches.
+ */
+declare function evaluateFilterQuery(query: FilterQuery, record: unknown, fields: readonly FilterRecordField[], clock?: FilterClock): FilterEvaluation;
+//#endregion
+export { FilterRecordField as n, evaluateFilterQuery as r, FilterEvaluation as t };

package/dist/filter-query-o3b_GuyC.d.ts

@@ -0,0 +1,133 @@
+/// <reference lib="esnext.temporal" />
+import { B as ColumnMeta } from "./executor-CPyrQdjh.js";
+//#region src/list/filter-query.d.ts
+type FilterCombinator = "and" | "or";
+interface FilterRule<V = unknown> {
+  readonly id: string;
+  readonly type: "rule";
+  readonly path: readonly string[];
+  readonly operator: string;
+  readonly value?: V | undefined;
+  readonly negated?: boolean;
+}
+interface FilterGroupNode<V = unknown> {
+  readonly id: string;
+  readonly type: "group";
+  readonly combinator: FilterCombinator;
+  readonly rules: readonly FilterNode<V>[];
+}
+type FilterNode<V = unknown> = FilterRule<V> | FilterGroupNode<V>;
+type FilterQuery<V = unknown> = FilterGroupNode<V>;
+/** A calendar offset from today, resolved when the query runs. */
+interface FilterRelativeDate {
+  readonly unit: "day" | "week" | "month" | "year";
+  readonly offset: number;
+}
+/**
+ * A date value: an absolute `yyyy-MM-dd` day or a relative token, with an
+ * optional `HH:mm`.
+ */
+interface FilterDateValue {
+  readonly date?: string;
+  readonly relative?: FilterRelativeDate;
+  readonly time?: string;
+}
+type FilterOperatorArity = "none" | "one" | "many" | "range";
+/**
+ * The value types a list filter field takes. `date` and `relation` map onto
+ * ReUI editors.
+ */
+type FilterFieldType = "text" | "number" | "date" | "select" | "multiselect" | "boolean" | "relation";
+interface FilterOperatorSpec {
+  readonly value: string;
+  readonly arity: FilterOperatorArity;
+  readonly inverse?: string;
+}
+/** The operators each field type allows, in the order ReUI lists them. */
+declare const FILTER_OPERATORS: Readonly<Record<FilterFieldType, readonly FilterOperatorSpec[]>>;
+/** English operator labels, the defaults `filterFields` uses. */
+declare const FILTER_OPERATOR_LABELS: Readonly<Record<string, string>>;
+/** One entry of `defineListQuery`'s `filters`: a field the tree may name. */
+interface ListFilterConfig<C extends string = string> {
+  readonly type: FilterFieldType;
+  /** The column the field filters; defaults to the field id. */
+  readonly column?: C;
+  readonly label?: string;
+  readonly description?: string;
+  /** A subset of the type's operators. */
+  readonly operators?: readonly string[];
+  readonly defaultOperator?: string;
+  /**
+   * Allowed values for `select` and `multiselect`; defaults to the column's
+   * enum.
+   */
+  readonly options?: readonly (string | {
+    readonly value: string;
+    readonly label?: string;
+  })[];
+}
+/** A checked filter field. */
+interface FilterFieldInfo {
+  readonly id: string;
+  readonly type: FilterFieldType;
+  /** Model key of the column. */
+  readonly column: string;
+  readonly columnMeta: ColumnMeta;
+  readonly label: string;
+  readonly description?: string;
+  readonly operators: readonly FilterOperatorSpec[];
+  readonly defaultOperator?: string;
+  readonly options?: readonly {
+    readonly value: string;
+    readonly label: string;
+  }[];
+}
+interface FilterLimits {
+  readonly maxDepth: number;
+  readonly maxRules: number;
+  readonly maxValueLength: number;
+  readonly maxValues: number;
+}
+interface FilterClock {
+  /** IANA time zone dates resolve in. Defaults to `UTC`. */
+  readonly timeZone?: string;
+  /** The current instant; defaults to `Temporal.Now`. */
+  readonly now?: Temporal.Instant;
+}
+/** The structural `FilterField` objects ReUI Filters takes. */
+interface FilterField {
+  readonly id: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly type?: "text" | "number" | "select" | "multiselect" | "boolean";
+  readonly options?: readonly {
+    readonly value: string;
+    readonly label: string;
+  }[];
+  readonly operators?: readonly {
+    readonly value: string;
+    readonly label: string;
+    readonly arity: FilterOperatorArity;
+    readonly inverse?: string;
+  }[];
+  readonly defaultOperator?: string;
+  /** The column the field filters. */
+  readonly column: string;
+}
+interface FilterFieldLabels {
+  /** Field labels by field id. */
+  readonly fields?: Readonly<Record<string, string>>;
+  /** Operator labels by operator value. */
+  readonly operators?: Readonly<Record<string, string>>;
+  /** Option labels by field id, then by option value. */
+  readonly options?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+/** `base64url` of the tree's JSON, for one URL parameter. */
+declare function encodeFilterQuery(query: FilterQuery): string;
+/**
+ * The JSON a `filter` URL parameter holds, or `undefined` when it is not
+ * base64url JSON.
+ */
+declare function decodeFilterQuery(encoded: string): unknown;
+//#endregion
+export { FilterRule as _, FilterDateValue as a, encodeFilterQuery as b, FilterFieldLabels as c, FilterLimits as d, FilterNode as f, FilterRelativeDate as g, FilterQuery as h, FilterCombinator as i, FilterFieldType as l, FilterOperatorSpec as m, FILTER_OPERATOR_LABELS as n, FilterField as o, FilterOperatorArity as p, FilterClock as r, FilterFieldInfo as s, FILTER_OPERATORS as t, FilterGroupNode as u, ListFilterConfig as v, decodeFilterQuery as y };

package/dist/flags-BTDPaN11.d.ts

@@ -0,0 +1,246 @@
+import { T as ErrorMapper } from "./result-C6jDfedy.js";
+import { r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.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 };