@guidelytech/flags 0.0.0-stage → 0.7.0

package/dist/evaluate.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Wire format of the feature-flag payload served by `GET /api/v1/sdk/flags` and the results of
+ * evaluating it. See docs/feature-flags-spec.md for the semantics; every SDK shares them.
+ */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type Attributes = Record<string, unknown>;
+type FlagValueType = "boolean" | "string" | "number" | "json";
+interface FlagsPayload {
+    schemaVersion: 1;
+    projectId: string;
+    environment: string;
+    /** Bumps on every change that affects this environment. */
+    version: number;
+    generatedAt: string;
+    /** Salt for the hashed (confidential) operators. */
+    salt: string;
+    flags: Record<string, FlagDefinition>;
+    segments: Record<string, SegmentDefinition>;
+    holdouts?: HoldoutDefinition[];
+}
+/** What `GET /flags` returns when the environment encrypts its payload. */
+interface EncryptedFlagsPayload {
+    schemaVersion: 1;
+    projectId: string;
+    environment: string;
+    version: number;
+    generatedAt: string;
+    encryptedPayload: string;
+}
+interface FlagDefinition {
+    key: string;
+    type: FlagValueType;
+    version: number;
+    /** Environment kill switch. */
+    enabled: boolean;
+    /** Served when the flag is disabled or a prerequisite fails. */
+    offValue: JsonValue;
+    /** Served when the flag is enabled and no rule serves a value. */
+    defaultValue: JsonValue;
+    prerequisites?: Prerequisite[];
+    rules?: FlagRule[];
+}
+type FlagComparisonOperator = "isOn" | "isOff" | "equals" | "notEquals";
+interface Prerequisite {
+    flag: string;
+    operator: FlagComparisonOperator;
+    value?: JsonValue;
+}
+interface RuleSchedule {
+    start?: string | null;
+    end?: string | null;
+}
+interface RuleBase {
+    id: string;
+    description?: string;
+    /** All must match; absent or empty means everyone. */
+    conditions?: Condition[];
+    schedule?: RuleSchedule;
+}
+interface ForceRule extends RuleBase {
+    type: "force";
+    value: JsonValue;
+    variationId?: string;
+}
+interface RampStep {
+    at: string;
+    coverage: number;
+}
+interface RolloutRule extends RuleBase {
+    type: "rollout";
+    value: JsonValue;
+    variationId?: string;
+    hashAttribute: string;
+    seed: string;
+    /** Share of matching users (0–1) that get `value`; the rest fall through. */
+    coverage: number;
+    /** Scheduled ramp: the coverage of the last step whose `at` has passed applies. */
+    ramp?: RampStep[];
+}
+interface SplitBucket {
+    weight: number;
+    value: JsonValue;
+    variationId?: string;
+}
+interface SplitRule extends RuleBase {
+    type: "split";
+    hashAttribute: string;
+    seed: string;
+    buckets: SplitBucket[];
+}
+interface ExperimentVariation {
+    id: string;
+    name?: string;
+    value: JsonValue;
+    weight: number;
+}
+interface ExperimentNamespace {
+    id: string;
+    start: number;
+    end: number;
+}
+interface ExperimentRule extends RuleBase {
+    type: "experiment";
+    key: string;
+    name?: string;
+    hashAttribute: string;
+    fallbackAttribute?: string;
+    seed: string;
+    coverage: number;
+    variations: ExperimentVariation[];
+    namespace?: ExperimentNamespace;
+    bucketVersion?: number;
+    minBucketVersion?: number;
+    disableStickyBucketing?: boolean;
+}
+type FlagRule = ForceRule | RolloutRule | SplitRule | ExperimentRule;
+type FlagRuleType = FlagRule["type"];
+declare const TEXT_OPERATORS: readonly ["equals", "notEquals", "in", "notIn", "contains", "notContains", "startsWith", "notStartsWith", "endsWith", "notEndsWith", "regex", "notRegex"];
+declare const NUMBER_OPERATORS: readonly ["numEquals", "numNotEquals", "gt", "gte", "lt", "lte"];
+declare const SEMVER_OPERATORS: readonly ["semverEquals", "semverNotEquals", "semverGt", "semverGte", "semverLt", "semverLte", "semverIn", "semverNotIn"];
+declare const DATE_OPERATORS: readonly ["before", "after"];
+declare const ARRAY_OPERATORS: readonly ["arrayContainsAny", "arrayNotContainsAny", "arrayContainsAll"];
+declare const BOOLEAN_OPERATORS: readonly ["isTrue", "isFalse"];
+declare const PRESENCE_OPERATORS: readonly ["exists", "notExists", "isType"];
+declare const HASHED_OPERATORS: readonly ["equalsHashed", "notEqualsHashed", "inHashed", "notInHashed", "startsWithHashed", "notStartsWithHashed", "endsWithHashed", "notEndsWithHashed", "arrayContainsAnyHashed", "arrayNotContainsAnyHashed"];
+declare const ATTRIBUTE_OPERATORS: readonly ["equals", "notEquals", "in", "notIn", "contains", "notContains", "startsWith", "notStartsWith", "endsWith", "notEndsWith", "regex", "notRegex", "numEquals", "numNotEquals", "gt", "gte", "lt", "lte", "semverEquals", "semverNotEquals", "semverGt", "semverGte", "semverLt", "semverLte", "semverIn", "semverNotIn", "before", "after", "arrayContainsAny", "arrayNotContainsAny", "arrayContainsAll", "isTrue", "isFalse", "exists", "notExists", "isType", "equalsHashed", "notEqualsHashed", "inHashed", "notInHashed", "startsWithHashed", "notStartsWithHashed", "endsWithHashed", "notEndsWithHashed", "arrayContainsAnyHashed", "arrayNotContainsAnyHashed"];
+type AttributeOperator = (typeof ATTRIBUTE_OPERATORS)[number];
+interface AttributeCondition {
+    kind: "attribute";
+    attribute: string;
+    operator: AttributeOperator;
+    values?: JsonValue[];
+    caseInsensitive?: boolean;
+}
+interface SegmentCondition {
+    kind: "segment";
+    operator: "in" | "notIn";
+    segment: string;
+}
+interface FlagCondition {
+    kind: "flag";
+    flag: string;
+    operator: FlagComparisonOperator;
+    value?: JsonValue;
+}
+interface GroupCondition {
+    kind: "group";
+    op: "and" | "or";
+    negate?: boolean;
+    conditions: Condition[];
+}
+type Condition = AttributeCondition | SegmentCondition | FlagCondition | GroupCondition;
+interface ConditionSegment {
+    key: string;
+    kind: "conditions";
+    conditions: Condition[];
+}
+interface ListSegment {
+    key: string;
+    kind: "list";
+    attribute: string;
+    values: string[];
+    hashed?: boolean;
+}
+type SegmentDefinition = ConditionSegment | ListSegment;
+interface HoldoutDefinition {
+    key: string;
+    hashAttribute: string;
+    seed: string;
+    coverage: number;
+    flags: string[];
+}
+type EvaluationReason = "FLAG_NOT_FOUND" | "DISABLED" | "PREREQUISITE_FAILED" | "HOLDOUT" | "RULE_MATCH" | "EXPERIMENT" | "DEFAULT" | "OVERRIDE" | "ERROR";
+interface ExperimentAssignment {
+    key: string;
+    name?: string;
+    variationId: string;
+    variationName?: string;
+    variationIndex: number;
+    hashAttribute: string;
+    hashValue: string;
+    bucket: number;
+    stickyBucketUsed: boolean;
+}
+interface EvaluationResult<T = JsonValue> {
+    key: string;
+    value: T | null;
+    reason: EvaluationReason;
+    ruleId?: string;
+    variationId?: string;
+    inExperiment: boolean;
+    experiment?: ExperimentAssignment;
+    errorMessage?: string;
+}
+/** Sticky bucket documents: `"<attribute>||<value>"` → `{ "<experimentKey>__<bucketVersion>": variationId }`. */
+type StickyAssignments = Record<string, string>;
+interface StickyBucketStore {
+    get(docKey: string): StickyAssignments | null | undefined;
+    set(docKey: string, assignments: StickyAssignments): void;
+}
+/** Response of `POST /api/v1/sdk/flags/evaluate`. */
+interface RemoteEvaluationResponse {
+    version: number;
+    flags: Record<string, EvaluationResult>;
+}
+/** Body of `POST /api/v1/sdk/flags/events`. */
+interface FlagEventsBatch {
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    usage?: Array<{
+        flag: string;
+        variationId?: string;
+        value?: string;
+        count: number;
+    }>;
+    exposures?: Array<{
+        experiment: string;
+        flag?: string;
+        variationId: string;
+        hashAttribute: string;
+        hashValue: string;
+        userId?: string;
+        anonymousId?: string;
+        timestamp: string;
+    }>;
+}
+
+declare function fnv1a32(bytes: Uint8Array): number;
+/** Deterministic bucket in [0, 1) with 4 decimals (GrowthBook hash v2 for ASCII input). */
+declare function hashBucket(seed: string, value: string): number;
+/** Lowercase hex SHA-256 of the UTF-8 bytes of `input`. */
+declare function sha256Hex(input: string | Uint8Array): string;
+/** `H(x)` for the hashed operators: SHA-256 of `salt + value`. */
+declare function hashConfidential(salt: string, value: string | Uint8Array): string;
+/** Comparison value for the hashed prefix/suffix operators: `"<byteLength>_<H(part)>"`. */
+declare function hashConfidentialAffix(salt: string, part: string): string;
+
+/** Value conversions used by the condition operators (docs/feature-flags-spec.md §3.2–3.3). */
+/** Text form of a scalar, or `undefined` for arrays, objects, null and non-finite numbers. */
+declare function textOf(v: unknown): string | undefined;
+declare function numberOf(v: unknown): number | undefined;
+interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string[];
+}
+declare function parseSemver(v: unknown): SemVer | undefined;
+/** SemVer 2.0 precedence: -1, 0 or 1. */
+declare function compareSemver(a: SemVer, b: SemVer): number;
+/** Milliseconds since the epoch: numbers are Unix seconds, strings ISO 8601, Date objects as-is. */
+declare function instantOf(v: unknown): number | undefined;
+/** JSON deep equality; numbers compare numerically, object keys unordered. */
+declare function jsonEquals(a: unknown, b: unknown): boolean;
+/** `isOn`: anything except null, false, 0 and "". */
+declare function isOn(v: unknown): boolean;
+
+interface EvaluateOptions {
+    /** Evaluation time (default: now). */
+    now?: Date | number | string;
+    /** Sticky bucketing store; experiments keep a user's variation across config changes. */
+    stickyBuckets?: StickyBucketStore;
+}
+/** Attribute by literal key, then by dot path. `null` counts as missing (`undefined`). */
+declare function lookupAttribute(attributes: Attributes, name: string): unknown;
+declare function isScheduleActive(schedule: RuleSchedule | undefined, now: number): boolean;
+declare function effectiveCoverage(rule: {
+    coverage: number;
+    ramp?: Array<{
+        at: string;
+        coverage: number;
+    }>;
+}, now: number): number;
+/** Evaluate one flag. Never throws: problems come back as reason `ERROR`. */
+declare function evaluateFlag(payload: FlagsPayload, key: string, attributes?: Attributes, options?: EvaluateOptions): EvaluationResult;
+/** Evaluate every flag in the payload. */
+declare function evaluateAllFlags(payload: FlagsPayload, attributes?: Attributes, options?: EvaluateOptions): Record<string, EvaluationResult>;
+
+export { ARRAY_OPERATORS, ATTRIBUTE_OPERATORS, type AttributeCondition, type AttributeOperator, type Attributes, BOOLEAN_OPERATORS, type Condition, type ConditionSegment, DATE_OPERATORS, type EncryptedFlagsPayload, type EvaluateOptions, type EvaluationReason, type EvaluationResult, type ExperimentAssignment, type ExperimentNamespace, type ExperimentRule, type ExperimentVariation, type FlagComparisonOperator, type FlagCondition, type FlagDefinition, type FlagEventsBatch, type FlagRule, type FlagRuleType, type FlagValueType, type FlagsPayload, type ForceRule, type GroupCondition, HASHED_OPERATORS, type HoldoutDefinition, type JsonValue, type ListSegment, NUMBER_OPERATORS, PRESENCE_OPERATORS, type Prerequisite, type RampStep, type RemoteEvaluationResponse, type RolloutRule, type RuleSchedule, SEMVER_OPERATORS, type SegmentCondition, type SegmentDefinition, type SplitBucket, type SplitRule, type StickyAssignments, type StickyBucketStore, TEXT_OPERATORS, compareSemver, effectiveCoverage, evaluateAllFlags, evaluateFlag, fnv1a32, hashBucket, hashConfidential, hashConfidentialAffix, instantOf, isOn, isScheduleActive, jsonEquals, lookupAttribute, numberOf, parseSemver, sha256Hex, textOf };

package/dist/evaluate.js

@@ -0,0 +1,57 @@
+import {
+  ARRAY_OPERATORS,
+  ATTRIBUTE_OPERATORS,
+  BOOLEAN_OPERATORS,
+  DATE_OPERATORS,
+  HASHED_OPERATORS,
+  NUMBER_OPERATORS,
+  PRESENCE_OPERATORS,
+  SEMVER_OPERATORS,
+  TEXT_OPERATORS,
+  compareSemver,
+  effectiveCoverage,
+  evaluateAllFlags,
+  evaluateFlag,
+  fnv1a32,
+  hashBucket,
+  hashConfidential,
+  hashConfidentialAffix,
+  instantOf,
+  isOn,
+  isScheduleActive,
+  jsonEquals,
+  lookupAttribute,
+  numberOf,
+  parseSemver,
+  sha256Hex,
+  textOf
+} from "./chunk-OY4QS3WL.js";
+export {
+  ARRAY_OPERATORS,
+  ATTRIBUTE_OPERATORS,
+  BOOLEAN_OPERATORS,
+  DATE_OPERATORS,
+  HASHED_OPERATORS,
+  NUMBER_OPERATORS,
+  PRESENCE_OPERATORS,
+  SEMVER_OPERATORS,
+  TEXT_OPERATORS,
+  compareSemver,
+  effectiveCoverage,
+  evaluateAllFlags,
+  evaluateFlag,
+  fnv1a32,
+  hashBucket,
+  hashConfidential,
+  hashConfidentialAffix,
+  instantOf,
+  isOn,
+  isScheduleActive,
+  jsonEquals,
+  lookupAttribute,
+  numberOf,
+  parseSemver,
+  sha256Hex,
+  textOf
+};
+//# sourceMappingURL=evaluate.js.map

package/dist/evaluate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}