@shelbyb/daywalker-sdk 0.1.4 → 0.3.0

package/dist/flags/engine/operators.js

@@ -0,0 +1,139 @@
+import { compareSemVer, parseSemVer } from "./semver.js";
+const regexCache = new Map();
+/** `matches` limits: longer inputs or patterns never match. */
+export const MAX_MATCH_INPUT_LENGTH = 1024;
+export const MAX_MATCH_PATTERN_LENGTH = 500;
+let warnedUnsafePattern = false;
+/**
+ * Conservative ReDoS heuristic: a group that contains a quantifier or alternation and is itself
+ * repeated (`(a+)+`, `(a*)*`, `(a|aa)+`, `(?:x+y)*`, `(a+){2,}`). Character classes and escapes are skipped.
+ */
+export function hasNestedQuantifier(pattern) {
+    const stack = []; // per open group: contains a quantifier / alternation
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "\\") {
+            i++;
+        }
+        else if (ch === "[") {
+            for (i++; i < pattern.length && pattern[i] !== "]"; i++)
+                if (pattern[i] === "\\")
+                    i++;
+        }
+        else if (ch === "(") {
+            stack.push(false);
+            if (pattern[i + 1] === "?")
+                i++; // group modifier, not a quantifier
+        }
+        else if (ch === ")") {
+            const risky = stack.pop() ?? false;
+            const next = pattern[i + 1];
+            const repeated = next === "*" || next === "+" || next === "{";
+            if (risky && repeated)
+                return true;
+            if ((risky || repeated) && stack.length)
+                stack[stack.length - 1] = true;
+        }
+        else if ((ch === "*" || ch === "+" || ch === "?" || ch === "{" || ch === "|") && stack.length) {
+            stack[stack.length - 1] = true;
+        }
+    }
+    return false;
+}
+function regex(pattern) {
+    if (!regexCache.has(pattern)) {
+        let re = null;
+        if (pattern.length > MAX_MATCH_PATTERN_LENGTH || hasNestedQuantifier(pattern)) {
+            if (!warnedUnsafePattern) {
+                warnedUnsafePattern = true;
+                console.warn("DevPulse: a `matches` pattern was too long or had nested quantifiers and is treated as no match");
+            }
+        }
+        else {
+            try {
+                re = new RegExp(pattern);
+            }
+            catch {
+                re = null;
+            }
+        }
+        if (regexCache.size > 1000)
+            regexCache.clear();
+        regexCache.set(pattern, re);
+    }
+    return regexCache.get(pattern);
+}
+/** RFC 3339 timestamp or Unix milliseconds → epoch ms. */
+export function parseTime(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    if (typeof v !== "string")
+        return null;
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/i.test(v))
+        return null;
+    const t = Date.parse(v);
+    return Number.isNaN(t) ? null : t;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return ka.length === kb.length && ka.every((k) => deepEqual(a[k], b[k]));
+}
+/** Compare one context value with one clause value. Type mismatches never match. */
+export function applyOperator(op, actual, expected) {
+    switch (op) {
+        case "in":
+            return deepEqual(actual, expected);
+        case "endsWith":
+            return typeof actual === "string" && typeof expected === "string" && actual.endsWith(expected);
+        case "startsWith":
+            return typeof actual === "string" && typeof expected === "string" && actual.startsWith(expected);
+        case "contains":
+            return typeof actual === "string" && typeof expected === "string" && actual.includes(expected);
+        case "matches": {
+            if (typeof actual !== "string" || typeof expected !== "string")
+                return false;
+            if (actual.length > MAX_MATCH_INPUT_LENGTH)
+                return false;
+            return regex(expected)?.test(actual) ?? false;
+        }
+        case "lessThan":
+        case "lessThanOrEqual":
+        case "greaterThan":
+        case "greaterThanOrEqual": {
+            if (typeof actual !== "number" || typeof expected !== "number")
+                return false;
+            if (op === "lessThan")
+                return actual < expected;
+            if (op === "lessThanOrEqual")
+                return actual <= expected;
+            if (op === "greaterThan")
+                return actual > expected;
+            return actual >= expected;
+        }
+        case "before":
+        case "after": {
+            const a = parseTime(actual);
+            const e = parseTime(expected);
+            if (a === null || e === null)
+                return false;
+            return op === "before" ? a < e : a > e;
+        }
+        case "semVerEqual":
+        case "semVerLessThan":
+        case "semVerGreaterThan": {
+            const a = parseSemVer(actual);
+            const e = parseSemVer(expected);
+            if (!a || !e)
+                return false;
+            const c = compareSemVer(a, e);
+            return op === "semVerEqual" ? c === 0 : op === "semVerLessThan" ? c < 0 : c > 0;
+        }
+    }
+}

package/dist/flags/engine/semver.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Semantic Versioning 2.0.0 comparison. Like LaunchDarkly, versions missing a
+ * minor or patch component ("2" or "2.1") are accepted and padded with zeros.
+ */
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string[];
+}
+export declare function parseSemVer(input: unknown): SemVer | null;
+/** Precedence per SemVer §11. Build metadata is ignored. */
+export declare function compareSemVer(a: SemVer, b: SemVer): number;

package/dist/flags/engine/semver.js

@@ -0,0 +1,35 @@
+const RE = /^v?(0|[1-9]\d*)(?:\.(0|[1-9]\d*))?(?:\.(0|[1-9]\d*))?(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+export function parseSemVer(input) {
+    if (typeof input !== "string")
+        return null;
+    const m = RE.exec(input.trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2] ?? 0), patch: Number(m[3] ?? 0), prerelease: m[4] ? m[4].split(".") : [] };
+}
+/** Precedence per SemVer §11. Build metadata is ignored. */
+export function compareSemVer(a, b) {
+    for (const k of ["major", "minor", "patch"])
+        if (a[k] !== b[k])
+            return a[k] < b[k] ? -1 : 1;
+    if (!a.prerelease.length || !b.prerelease.length)
+        return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length ? -1 : 1;
+    for (let i = 0; i < Math.max(a.prerelease.length, b.prerelease.length); i++) {
+        const x = a.prerelease[i];
+        const y = b.prerelease[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        if (x === y)
+            continue;
+        const xn = /^\d+$/.test(x);
+        const yn = /^\d+$/.test(y);
+        if (xn && yn)
+            return Number(x) < Number(y) ? -1 : 1;
+        if (xn !== yn)
+            return xn ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}

package/dist/flags/engine/sha1.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Synchronous SHA-1 (FIPS 180-4) over UTF-8 strings. Used only for
+ * deterministic bucketing, never for security, and kept dependency-free so the
+ * engine runs unchanged in Node, browsers, workers and edge runtimes.
+ */
+export declare function sha1Hex(message: string): string;

package/dist/flags/engine/sha1.js

@@ -0,0 +1,43 @@
+/**
+ * Synchronous SHA-1 (FIPS 180-4) over UTF-8 strings. Used only for
+ * deterministic bucketing, never for security, and kept dependency-free so the
+ * engine runs unchanged in Node, browsers, workers and edge runtimes.
+ */
+export function sha1Hex(message) {
+    const bytes = new TextEncoder().encode(message);
+    const len = bytes.length;
+    const words = new Uint32Array((((len + 8) >> 6) + 1) * 16);
+    for (let i = 0; i < len; i++)
+        words[i >> 2] |= bytes[i] << (24 - (i % 4) * 8);
+    words[len >> 2] |= 0x80 << (24 - (len % 4) * 8);
+    const bitLen = len * 8;
+    words[words.length - 2] = Math.floor(bitLen / 0x100000000);
+    words[words.length - 1] = bitLen >>> 0;
+    let h0 = 0x67452301, h1 = 0xefcdab89, h2 = 0x98badcfe, h3 = 0x10325476, h4 = 0xc3d2e1f0;
+    const w = new Uint32Array(80);
+    for (let block = 0; block < words.length; block += 16) {
+        for (let t = 0; t < 16; t++)
+            w[t] = words[block + t];
+        for (let t = 16; t < 80; t++) {
+            const x = w[t - 3] ^ w[t - 8] ^ w[t - 14] ^ w[t - 16];
+            w[t] = (x << 1) | (x >>> 31);
+        }
+        let a = h0, b = h1, c = h2, d = h3, e = h4;
+        for (let t = 0; t < 80; t++) {
+            const f = t < 20 ? (b & c) | (~b & d) : t < 40 ? b ^ c ^ d : t < 60 ? (b & c) | (b & d) | (c & d) : b ^ c ^ d;
+            const k = t < 20 ? 0x5a827999 : t < 40 ? 0x6ed9eba1 : t < 60 ? 0x8f1bbcdc : 0xca62c1d6;
+            const temp = (((a << 5) | (a >>> 27)) + f + e + k + w[t]) >>> 0;
+            e = d;
+            d = c;
+            c = (b << 30) | (b >>> 2);
+            b = a;
+            a = temp;
+        }
+        h0 = (h0 + a) >>> 0;
+        h1 = (h1 + b) >>> 0;
+        h2 = (h2 + c) >>> 0;
+        h3 = (h3 + d) >>> 0;
+        h4 = (h4 + e) >>> 0;
+    }
+    return [h0, h1, h2, h3, h4].map((h) => (h >>> 0).toString(16).padStart(8, "0")).join("");
+}

package/dist/flags/engine/types.d.ts

@@ -0,0 +1,120 @@
+/** JSON-compatible flag values. */
+export type FlagValue = boolean | string | number | null | FlagValue[] | {
+    [key: string]: FlagValue;
+};
+export declare const OPERATORS: readonly ["in", "endsWith", "startsWith", "matches", "contains", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual", "before", "after", "semVerEqual", "semVerLessThan", "semVerGreaterThan", "segmentMatch"];
+export type Operator = (typeof OPERATORS)[number];
+export interface Clause {
+    /** Context kind the attribute belongs to. Defaults to "user". */
+    contextKind?: string;
+    /** Attribute name, or an RFC 6901 JSON Pointer when it starts with "/". */
+    attribute: string;
+    op: Operator;
+    values: FlagValue[];
+    negate?: boolean;
+}
+export interface WeightedVariation {
+    variation: number;
+    /** 0..100000 (thousandths of a percent). */
+    weight: number;
+    /** Excluded from experiment analysis even inside an experiment rollout. */
+    untracked?: boolean;
+}
+export interface Rollout {
+    kind?: "rollout" | "experiment";
+    contextKind?: string;
+    bucketBy?: string;
+    /** Experiments use a fixed seed so re-running a flag config keeps buckets stable. */
+    seed?: number;
+    variations: WeightedVariation[];
+}
+/** A variation index or a rollout. */
+export interface VariationOrRollout {
+    variation?: number;
+    rollout?: Rollout;
+}
+export interface Rule extends VariationOrRollout {
+    id: string;
+    description?: string;
+    clauses: Clause[];
+    trackEvents?: boolean;
+}
+export interface Target {
+    contextKind?: string;
+    variation: number;
+    values: string[];
+}
+export interface Prerequisite {
+    key: string;
+    variation: number;
+}
+/** A flag as evaluated in one environment. */
+export interface FlagConfig {
+    key: string;
+    version: number;
+    on: boolean;
+    salt: string;
+    variations: FlagValue[];
+    offVariation: number | null;
+    fallthrough: VariationOrRollout;
+    targets: Target[];
+    rules: Rule[];
+    prerequisites: Prerequisite[];
+    clientSide?: boolean;
+    trackEvents?: boolean;
+    trackEventsFallthrough?: boolean;
+    deleted?: boolean;
+}
+export interface SegmentRule {
+    id: string;
+    clauses: Clause[];
+    /** Optional: include only this fraction of matching contexts (0..100000). */
+    weight?: number;
+    rolloutContextKind?: string;
+    bucketBy?: string;
+}
+export interface SegmentConfig {
+    key: string;
+    version: number;
+    salt: string;
+    included: Target[] | {
+        contextKind?: string;
+        values: string[];
+    }[];
+    excluded: {
+        contextKind?: string;
+        values: string[];
+    }[];
+    rules: SegmentRule[];
+    deleted?: boolean;
+}
+export type ErrorKind = "FLAG_NOT_FOUND" | "MALFORMED_FLAG" | "USER_NOT_SPECIFIED" | "WRONG_TYPE" | "CLIENT_NOT_READY" | "EXCEPTION";
+export type EvaluationReason = {
+    kind: "OFF";
+} | {
+    kind: "FALLTHROUGH";
+    inExperiment?: boolean;
+} | {
+    kind: "TARGET_MATCH";
+} | {
+    kind: "RULE_MATCH";
+    ruleIndex: number;
+    ruleId: string;
+    inExperiment?: boolean;
+} | {
+    kind: "PREREQUISITE_FAILED";
+    prerequisiteKey: string;
+} | {
+    kind: "ERROR";
+    errorKind: ErrorKind;
+};
+export interface EvaluationDetail<T = FlagValue> {
+    value: T;
+    variationIndex: number | null;
+    reason: EvaluationReason;
+}
+/** Read-only access to flags and segments for one environment. */
+export interface DataStore {
+    getFlag(key: string): FlagConfig | undefined;
+    getSegment(key: string): SegmentConfig | undefined;
+}

package/dist/flags/engine/types.js

@@ -0,0 +1,17 @@
+export const OPERATORS = [
+    "in",
+    "endsWith",
+    "startsWith",
+    "matches",
+    "contains",
+    "lessThan",
+    "lessThanOrEqual",
+    "greaterThan",
+    "greaterThanOrEqual",
+    "before",
+    "after",
+    "semVerEqual",
+    "semVerLessThan",
+    "semVerGreaterThan",
+    "segmentMatch",
+];

package/dist/flags/node.d.ts

@@ -0,0 +1,97 @@
+import { EventEmitter } from "node:events";
+import { type ContextInput, type EvaluationDetail, type FlagConfig, type FlagValue, type SegmentConfig } from "./engine/index.js";
+import { type Logger } from "./common/index.js";
+export type { ContextInput, EvaluationDetail, FlagValue, Logger };
+export interface NodeClientOptions {
+    /** Base URL of your DevPulse deployment (https required except on localhost). */
+    baseUrl: string;
+    /** Real-time updates over SSE (default). Set false to poll instead. */
+    stream?: boolean;
+    /** Poll interval when not streaming (and as a fallback). Minimum 30s. */
+    pollIntervalMs?: number;
+    sendEvents?: boolean;
+    flushIntervalMs?: number;
+    privateAttributes?: string[];
+    allAttributesPrivate?: boolean;
+    /** Never connect; every variation returns its default (useful in tests). */
+    offline?: boolean;
+    /** Start from fixed data (e.g. tests or a file); disables network. */
+    initialData?: {
+        flags?: Record<string, FlagConfig>;
+        segments?: Record<string, SegmentConfig>;
+    };
+    fetch?: typeof fetch;
+    logger?: Logger;
+}
+export interface AllFlagsState {
+    valid: boolean;
+    values: Record<string, FlagValue>;
+    /** Pass to the browser SDK's `bootstrap` option for flicker-free SSR. */
+    toJSON(): Record<string, {
+        value: FlagValue;
+        variation: number | null;
+        version: number;
+        reason?: unknown;
+    }>;
+}
+/**
+ * Server-side client. One instance per process and SDK key.
+ *
+ *   const client = init(process.env.DEVPULSE_SDK_KEY!, { baseUrl });
+ *   await client.waitForInitialization({ timeoutMs: 5000 });
+ *   const enabled = await client.variation("new-checkout", { key: user.id, email: user.email }, false);
+ */
+export declare class DevPulseNodeClient extends EventEmitter {
+    private readonly sdkKey;
+    private readonly options;
+    private store;
+    private stream;
+    private poller;
+    private etag;
+    private events;
+    private initialized;
+    private ready;
+    private resolveReady;
+    private rejectReady;
+    private streamFailures;
+    private readonly logger;
+    private readonly base;
+    constructor(sdkKey: string, options: NodeClientOptions);
+    private headers;
+    private startStreaming;
+    private startPolling;
+    private stopPolling;
+    private onStreamEvent;
+    private applyPut;
+    private emitUpdate;
+    private markReady;
+    private fail;
+    waitForInitialization(opts?: {
+        timeoutMs?: number;
+    }): Promise<this>;
+    get isInitialized(): boolean;
+    /** Evaluate a flag locally. Never throws; returns `defaultValue` on any problem. */
+    variationDetailSync<T extends FlagValue>(key: string, context: ContextInput, defaultValue: T): EvaluationDetail<T>;
+    variationSync<T extends FlagValue>(key: string, context: ContextInput, defaultValue: T): T;
+    variation<T extends FlagValue>(key: string, context: ContextInput, defaultValue: T): Promise<T>;
+    variationDetail<T extends FlagValue>(key: string, context: ContextInput, defaultValue: T): Promise<EvaluationDetail<T>>;
+    boolVariation(key: string, context: ContextInput, defaultValue: boolean): Promise<boolean>;
+    stringVariation(key: string, context: ContextInput, defaultValue: string): Promise<string>;
+    numberVariation(key: string, context: ContextInput, defaultValue: number): Promise<number>;
+    jsonVariation<T extends FlagValue>(key: string, context: ContextInput, defaultValue: T): Promise<T>;
+    /**
+     * Evaluate every flag for a context, e.g. to bootstrap a browser client
+     * during server rendering. Doesn't record analytics.
+     */
+    allFlagsState(context: ContextInput, opts?: {
+        clientSideOnly?: boolean;
+        withReasons?: boolean;
+    }): Promise<AllFlagsState>;
+    /** Secure mode hash for a context, for the browser SDK's `hash` option. */
+    secureModeHash(context: ContextInput): string;
+    track(key: string, context: ContextInput, data?: unknown, metricValue?: number): void;
+    identify(context: ContextInput): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function init(sdkKey: string, options: NodeClientOptions): DevPulseNodeClient;