@lucida-analytics/sdk-core 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 /** Result of one transport attempt. status 0 means a network failure. */
 interface TransportResult {
     status: number;
+    /** The response's Retry-After in ms (429/503), when the transport can read it. The queue waits at least this long (capped at 60 s). */
+    retryAfterMs?: number;
 }
 interface SendOptions {
     /** Fire-and-forget delivery that survives page unload (navigator.sendBeacon). */
@@ -187,6 +189,7 @@ declare class EventQueue {
     private attempt;
     private inflight;
     private closed;
+    private warned404;
     private readonly flushAt;
     private readonly intervalMs;
     private readonly maxSize;
@@ -686,6 +689,8 @@ type FilterOpV2 = "icontains" | "not_icontains" | "starts_with" | "not_starts_wi
 /** Operator semantics: port of go/internal/flageval/ops.go (the reference). */
 
 type FilterOp = "eq" | "neq" | "contains" | "ncontains" | "regex" | "nregex" | "gt" | "gte" | "lt" | "lte" | "is_set" | "is_not_set" | "in" | "not_in" | FilterOpV2 | FilterOpList;
+/** Missing/null properties match only is_not_set; every other op (even negations) is false. */
+declare function matchOp(op: FilterOp, prop: unknown, present: boolean, want: unknown, semver: boolean, nowMs?: number): boolean;
 
 interface PropertyFilter {
     /** `event_property` only inside an event filter's `properties`. */
@@ -889,7 +894,7 @@ declare class FlagFreshness {
 /**
  * Persistent sticky-bucketing store (LC-EXT-29): the value each unit got from a sticky flag, so it
  * keeps it when rollout or variant weights change. Keyed by the flag's bucketing key.
- * shortcut: synchronous port (fits memory and localStorage); preload async stores before evaluating.
+ * Synchronous (fits memory and localStorage); for an async backend use AsyncStickyStore + evaluateAllStickyAsync.
  */
 interface StickyStore {
     get(bucketingKey: string): Record<string, FlagValue> | undefined;
@@ -907,6 +912,18 @@ declare class MemoryStickyStore implements StickyStore {
 declare const stickyValue: (f: FlagDefinition, r: EvalResult) => FlagValue | undefined;
 /** evaluateAll with stored assignments loaded from `store` and fresh sticky matches written back. */
 declare function evaluateAllSticky(flags: FlagDefinition[], c: EvalContext, store: StickyStore): Record<string, EvalResult>;
+/** Sticky store whose reads and writes are asynchronous (Redis, a database, React Native storage). */
+interface AsyncStickyStore {
+    get(bucketingKey: string): Promise<Record<string, FlagValue> | undefined>;
+    set(bucketingKey: string, flagKey: string, value: FlagValue): Promise<void>;
+}
+/**
+ * evaluateAllSticky over an async store: the assignments of every bucketing key the sticky flags use are
+ * awaited first (so evaluation sees the stored values), evaluation runs on that snapshot, and the fresh
+ * matches are written back (queued, then awaited together). A failed read or write only means re-hashing
+ * next time; it never fails the evaluation.
+ */
+declare function evaluateAllStickyAsync(flags: FlagDefinition[], c: EvalContext, store: AsyncStickyStore): Promise<Record<string, EvalResult>>;
 
 /**
  * Migration flags (LC-FLG-24): a multivariate flag whose variants are the six stages of moving a data
@@ -1094,4 +1111,4 @@ declare class AgentConversation {
     outcome(outcome: AgentOutcome, resolution?: string): boolean;
 }
 
-export { AGENT_EVENTS, AGENT_NEG_PHRASES, AGENT_POS_PHRASES, AgentConversation, type AgentConversationOptions, type AgentFeedback, type AgentFeedbackKind, type AgentOutcome, type AgentRole, type Aggregation, type AiConfig, type AiConfigFallback, type AiMessage, type AiTool, type BackoffOptions, CONSENT_KEY, type CaptureExtras, type Clock, type ConditionGroup, Consent, type ConsentCategory, type ConsentDefault, type ConsentMode, type ConsentOptions, type ConsentState, type ConsentStatus, Core, type CoreChange, type CoreConfig, DISTINCT_ID_HEADER, EARLY_ACCESS_EVENT, type EarlyAccessFeature, type EarlyAccessService, type Enrichment, type EvalContext, type EvalReason, type EvalResult, EventQueue, type FilterOp, type FlagCacheStamp, type FlagDefinition, type FlagFallbacks, FlagFreshness, type FlagResult, FlagSnapshot, FlagStream, type FlagStreamOptions, type FlagSyncOptions, type FlagValue, GatedStorage, Groups, Identity, type Intervention, type InterventionHub, InterventionStream, type InterventionStreamOptions, MIGRATION_STAGES, MemoryStickyStore, type MigrationOps, type MigrationReport, type MigrationStage, type OfflineOptions, type OfflineTransport, type PropertyFilter, type Props, type QueueOptions, type RemoteSessionSettings, type RequestContext, type RuntimeBranch, RuntimeCounter, type RuntimeEvents, SESSION_ID_HEADER, type SendOptions, type RequestLike as ServerRequestLike, type SessionInfo, SessionManager, type SessionOptions, type SseMessage, type StickyStore, type Storage, SuperProps, type Transport, type TransportResult, type Variant, type WireEvent, agentCommonProps, agentFeedbackProps, agentMessageProps, agentOutcome, agentOutcomeProps, agentRedact, agentSentiment, agentTextHash, agentTraceId, aiConfig, backoffDelay, bucketingKey, cleanHeader, countKey, countedFilters, enrollmentCapture, enrollmentProp, evaluateAll, evaluateAllSticky, evaluateFlag, eventPropsMatch, fallbackValue, flagEventProps, flagHash, flagResult, interventionHub, isRetryable, mergePatch, migrateRead, migrateWrite, migrationStage, offlineTransport, requestContext, requiresServer, resolveRuntime, resolveRuntimeAll, routeTemplate, servable, sha256Hex, sseParser, startFlagSync, stickyValue, uuidv7, withFallback, withFlagProps };
+export { AGENT_EVENTS, AGENT_NEG_PHRASES, AGENT_POS_PHRASES, AgentConversation, type AgentConversationOptions, type AgentFeedback, type AgentFeedbackKind, type AgentOutcome, type AgentRole, type Aggregation, type AiConfig, type AiConfigFallback, type AiMessage, type AiTool, type AsyncStickyStore, type BackoffOptions, CONSENT_KEY, type CaptureExtras, type Clock, type ConditionGroup, Consent, type ConsentCategory, type ConsentDefault, type ConsentMode, type ConsentOptions, type ConsentState, type ConsentStatus, Core, type CoreChange, type CoreConfig, DISTINCT_ID_HEADER, EARLY_ACCESS_EVENT, type EarlyAccessFeature, type EarlyAccessService, type Enrichment, type EvalContext, type EvalReason, type EvalResult, EventQueue, type FilterOp, type FlagCacheStamp, type FlagDefinition, type FlagFallbacks, FlagFreshness, type FlagResult, FlagSnapshot, FlagStream, type FlagStreamOptions, type FlagSyncOptions, type FlagValue, GatedStorage, Groups, Identity, type Intervention, type InterventionHub, InterventionStream, type InterventionStreamOptions, MIGRATION_STAGES, MemoryStickyStore, type MigrationOps, type MigrationReport, type MigrationStage, type OfflineOptions, type OfflineTransport, type PropertyFilter, type Props, type QueueOptions, type RemoteSessionSettings, type RequestContext, type RuntimeBranch, RuntimeCounter, type RuntimeEvents, SESSION_ID_HEADER, type SendOptions, type RequestLike as ServerRequestLike, type SessionInfo, SessionManager, type SessionOptions, type SseMessage, type StickyStore, type Storage, SuperProps, type Transport, type TransportResult, type Variant, type WireEvent, agentCommonProps, agentFeedbackProps, agentMessageProps, agentOutcome, agentOutcomeProps, agentRedact, agentSentiment, agentTextHash, agentTraceId, aiConfig, backoffDelay, bucketingKey, cleanHeader, countKey, countedFilters, enrollmentCapture, enrollmentProp, evaluateAll, evaluateAllSticky, evaluateAllStickyAsync, evaluateFlag, eventPropsMatch, fallbackValue, flagEventProps, flagHash, flagResult, interventionHub, isRetryable, matchOp, mergePatch, migrateRead, migrateWrite, migrationStage, offlineTransport, requestContext, requiresServer, resolveRuntime, resolveRuntimeAll, routeTemplate, servable, sha256Hex, sseParser, startFlagSync, stickyValue, uuidv7, withFallback, withFlagProps };

package/dist/index.js

@@ -254,6 +254,7 @@ var EventQueue = class {
   attempt = 0;
   inflight;
   closed = false;
+  warned404 = false;
   flushAt;
   intervalMs;
   maxSize;
@@ -292,15 +293,15 @@ var EventQueue = class {
     const body = JSON.stringify({ api_key: this.o.apiKey, batch, sent_at: new Date(sentAt).toISOString() });
     this.o.log?.("send batch", batch.length);
     const p = this.o.transport.send(this.o.url, body, opts.beacon ? { beacon: true } : {}).then(
-      (r) => r.status,
-      () => 0
-    ).then((status) => this.settle(batch, status, !!opts.beacon)).finally(() => {
+      (r) => r,
+      () => ({ status: 0, retryAfterMs: void 0 })
+    ).then((r) => this.settle(batch, r.status, !!opts.beacon, r.retryAfterMs)).finally(() => {
       this.inflight = void 0;
     });
     this.inflight = p;
     return p;
   }
-  settle(batch, status, beacon) {
+  settle(batch, status, beacon, retryAfterMs) {
     if (status >= 200 && status < 300) {
       this.attempt = 0;
       if (this.items.length >= this.flushAt) void this.flush();
@@ -308,12 +309,18 @@ var EventQueue = class {
       return;
     }
     if (!isRetryable(status) || beacon || this.attempt >= this.maxRetries) {
+      if (status === 404 && !this.warned404) {
+        this.warned404 = true;
+        console.warn(
+          `[lucida] ${this.o.url} returned 404, so events are being dropped. apiHost is probably wrong: use https://capture.lucidace.com (or your own capture host), not the app host.`
+        );
+      }
       this.o.onDrop?.(batch, `status_${status}`);
       this.attempt = 0;
       return;
     }
     this.items.unshift(...batch);
-    const delay = backoffDelay(this.attempt++, this.o.backoff);
+    const delay = Math.max(backoffDelay(this.attempt++, this.o.backoff), Math.min(retryAfterMs ?? 0, 6e4));
     this.o.log?.("retry in", delay, "ms");
     this.arm(delay);
   }
@@ -335,14 +342,24 @@ var KEY2 = "lc_session";
 function minutes(v, lo, hi) {
   return typeof v === "number" && Number.isInteger(v) && v >= lo && v <= hi ? v * 6e4 : void 0;
 }
+var MIN_IDLE = 6e4;
+var MAX_IDLE = 10 * 36e5;
+var DAY = 24 * 36e5;
+var UUID7 = /^([0-9a-f]{8})-?([0-9a-f]{4})-7[0-9a-f]{3}-/i;
+function bootstrapOk(id, now) {
+  const m = UUID7.exec(id);
+  if (!m) return true;
+  const ts = parseInt(m[1] + m[2], 16);
+  return ts - now <= 6e4 && now - ts <= DAY;
+}
 var SessionManager = class {
   constructor(storage, o = {}) {
     this.storage = storage;
     this.o = o;
-    this.idleMs = o.idleMs ?? 30 * 6e4;
+    this.idleMs = Math.min(MAX_IDLE, Math.max(MIN_IDLE, o.idleMs ?? 30 * 6e4));
     this.maxMs = o.maxMs ?? 24 * 36e5;
     this.newOn = o.newOnEvents ?? [];
-    this.clock = o.clock ?? Date;
+    this.clock = o.clock ?? { now: () => Date.now() };
     this.bootstrapId = o.bootstrapId;
   }
   storage;
@@ -358,7 +375,7 @@ var SessionManager = class {
    * out-of-range remote values leave the current setting.
    */
   configure(r) {
-    if (this.o.idleMs === void 0) this.idleMs = minutes(r.session_idle_minutes, 1, 1440) ?? this.idleMs;
+    if (this.o.idleMs === void 0) this.idleMs = minutes(r.session_idle_minutes, 1, 600) ?? this.idleMs;
     if (this.o.maxMs === void 0) this.maxMs = minutes(r.session_max_minutes, 5, 10080) ?? this.maxMs;
     if (this.o.newOnEvents === void 0 && Array.isArray(r.session_new_on_events)) {
       this.newOn = r.session_new_on_events.filter((e) => typeof e === "string" && e !== "");
@@ -378,8 +395,8 @@ var SessionManager = class {
     let s = this.read();
     const campaignChanged = !!(s?.campaign && campaignKey && s.campaign !== campaignKey);
     const ruleEvent = event !== void 0 && this.newOn.includes(event);
-    const isNew = !s || now - s.last > this.idleMs || now - s.start > this.maxMs || campaignChanged || ruleEvent;
-    if (isNew || !s) s = { id: !s && this.bootstrapId || uuidv7(now), start: now, last: now };
+    const isNew = !s || Math.abs(now - s.last) > this.idleMs || Math.abs(now - s.start) > this.maxMs || campaignChanged || ruleEvent;
+    if (isNew || !s) s = { id: !s && this.bootstrapId && bootstrapOk(this.bootstrapId, now) ? this.bootstrapId : uuidv7(now), start: now, last: now };
     this.bootstrapId = void 0;
     s.last = now;
     if (campaignKey) s.campaign = campaignKey;
@@ -469,7 +486,7 @@ function validTime(t, now) {
 var Core = class {
   constructor(c) {
     this.c = c;
-    this.clock = c.clock ?? Date;
+    this.clock = c.clock ?? { now: () => Date.now() };
     this.consent = new Consent({ ...c.consent, storage: c.consentStorage ?? c.storage });
     this.gated = new GatedStorage(c.storage, () => this.consent.has("analytics"));
     this.storage = this.gated;
@@ -1800,23 +1817,27 @@ function evaluateAll(flags, c) {
   for (const f of flags) visit(f.key);
   return out;
 }
-var MAX_BRANCHED_DEPS = 4;
 function evaluateDependent(f, c, resolved) {
-  const pending = [];
-  for (const d of deps(f)) if (!pending.includes(d) && resolved[d]?.runtime?.length && pending.length < MAX_BRANCHED_DEPS) pending.push(d);
-  return evalOver(f, c, resolved, pending);
+  return evalOver(f, c, resolved, [], /* @__PURE__ */ new Set());
 }
-function evalOver(f, c, resolved, pending) {
+function evalOver(f, c, resolved, pending, done) {
   const [dep, ...rest] = pending;
-  if (dep === void 0) return evaluateFlag(f, c, resolved);
-  const base = evalOver(f, c, resolved, rest);
+  if (dep === void 0) {
+    const reads = /* @__PURE__ */ new Set();
+    const tracked = new Proxy(resolved, { get: (t, k) => (reads.add(String(k)), t[k]) });
+    const r = evaluateFlag(f, c, tracked);
+    const more = [];
+    for (const d of deps(f)) if (reads.has(d) && !done.has(d) && !more.includes(d) && resolved[d]?.runtime?.length) more.push(d);
+    return more.length ? evalOver(f, c, resolved, more, /* @__PURE__ */ new Set([...done, ...more])) : r;
+  }
+  const base = evalOver(f, c, resolved, rest, done);
   const cur = resolved[dep];
   const tried = /* @__PURE__ */ new Set([cur.value]);
   const branches = [];
   for (const alt of outcomes(cur)) {
     if (tried.has(alt.value)) continue;
     tried.add(alt.value);
-    const r = evalOver(f, c, { ...resolved, [dep]: alt }, rest);
+    const r = evalOver(f, c, { ...resolved, [dep]: alt }, rest, done);
     if (same(r, base)) continue;
     branches.push({ filters: [{ type: "flag", key: dep, op: "eq", value: alt.value }], result: r });
   }
@@ -1964,6 +1985,31 @@ function evaluateAllSticky(flags, c, store) {
   }
   return out;
 }
+async function evaluateAllStickyAsync(flags, c, store) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const f of flags) {
+    const k = f.sticky ? bucketingKey(f, c) : void 0;
+    if (k) keys.add(k);
+  }
+  const snapshot = new MemoryStickyStore();
+  const writes = [];
+  await Promise.all(
+    [...keys].map(async (k) => {
+      for (const [flag, v] of Object.entries(await store.get(k).catch(() => void 0) ?? {})) snapshot.set(k, flag, v);
+    })
+  );
+  const queued = {
+    get: (k) => snapshot.get(k),
+    set(k, flag, v) {
+      if (snapshot.get(k)?.[flag] === v) return;
+      snapshot.set(k, flag, v);
+      writes.push(store.set(k, flag, v).catch(() => void 0));
+    }
+  };
+  const out = evaluateAllSticky(flags, c, queued);
+  await Promise.all(writes);
+  return out;
+}
 
 // src/migration.ts
 var MIGRATION_STAGES = ["off", "dualwrite", "shadow", "live", "rampdown", "complete"];
@@ -2379,6 +2425,7 @@ export {
   enrollmentProp,
   evaluateAll,
   evaluateAllSticky,
+  evaluateAllStickyAsync,
   evaluateFlag,
   eventPropsMatch,
   fallbackValue,
@@ -2387,6 +2434,7 @@ export {
   flagResult,
   interventionHub,
   isRetryable,
+  matchOp,
   mergePatch,
   migrateRead,
   migrateWrite,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucida-analytics/sdk-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",