@fireweaveai/web-sdk 2.1.0

package/dist/runtime.js

@@ -0,0 +1,289 @@
+/**
+ * FireweaveWebRuntime — the async/sync boundary.
+ *
+ * `initialize()` and `setContext()` prefetch a decision cache asynchronously;
+ * `evaluateSync()` is a pure read of that cache. That split is what lets a
+ * synchronous OpenFeature web provider sit on top of an architecture that is
+ * otherwise async, without either side bending.
+ *
+ * ## Fail-open, not fail-silent
+ *
+ * A hung backend must not block app boot, so the prefetch races a ceiling. What
+ * happens when the ceiling wins is the design decision that matters: this
+ * runtime enters `STALE` — not `READY` — and serves defaults with reason
+ * `STALE`, so a timed-out boot is DISTINGUISHABLE from a successful one.
+ *
+ * The tempting alternative (resolve the race and carry on) makes a failed
+ * prefetch look exactly like a successful one where every control point
+ * happened to be off. Under a progressive rollout that is the difference
+ * between "nobody got the feature because the ramp is at 0%" and "nobody got
+ * the feature because the SDK never reached the server", and no operator can
+ * tell those apart after the fact.
+ */
+import { FireweaveError, isFireweaveError } from './errors.js';
+import { canonicalizeContext, DEFAULT_CONTEXT_LIMITS, mergeContexts } from './context.js';
+/** Ceiling on the initial prefetch so a hung backend cannot block boot. */
+export const DEFAULT_FLAGS_READY_TIMEOUT_MS = 5_000;
+function matchesExpectedType(value, expected) {
+    switch (expected) {
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number';
+        case 'object':
+            return typeof value === 'object' && value !== null;
+    }
+}
+export class FireweaveWebRuntime {
+    adapter;
+    config;
+    state = 'UNINITIALIZED';
+    cache = new Map();
+    globalContext;
+    limits;
+    releaseContext = {};
+    listeners = new Set();
+    constructor(adapter, config = {}) {
+        this.adapter = adapter;
+        this.config = config;
+        this.globalContext = { ...(config.globalContext ?? {}) };
+        this.limits = { ...DEFAULT_CONTEXT_LIMITS, ...(config.limits ?? {}) };
+    }
+    getState() {
+        return this.state;
+    }
+    onStateChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    setState(next) {
+        this.state = next;
+        for (const l of this.listeners)
+            l(next);
+    }
+    setReleaseContext(ctx) {
+        this.releaseContext = { ...ctx };
+    }
+    getReleaseContext() {
+        return this.releaseContext;
+    }
+    /** Initialize the adapter and populate the cache. Never throws. */
+    async initialize(context) {
+        if (this.state === 'SHUTDOWN')
+            return;
+        this.setState('INITIALIZING');
+        if (context !== undefined)
+            this.globalContext = mergeContexts(this.globalContext, context);
+        try {
+            await this.adapter.initialize();
+        }
+        catch {
+            this.setState('ERROR');
+            return;
+        }
+        await this.refresh();
+    }
+    /**
+     * Replace the global context and re-prefetch — the identity-change path.
+     *
+     * Call this after sign-in with the user's stable id, so percentage ramps
+     * bucket on that id rather than on an anonymous one. Returns the keys whose
+     * decisions changed, so a provider can emit a targeted ConfigurationChanged.
+     */
+    async setContext(context) {
+        this.globalContext = { ...context };
+        const before = this.cache;
+        await this.refresh();
+        return this.changedKeys(before, this.cache);
+    }
+    /** Re-run the prefetch against the current global context. */
+    async refresh() {
+        if (this.state === 'SHUTDOWN')
+            return;
+        let canonical;
+        try {
+            canonical = canonicalizeContext(this.globalContext, this.limits);
+        }
+        catch {
+            this.setState('ERROR');
+            return;
+        }
+        const timeoutMs = this.config.flagsReadyTimeoutMs ?? DEFAULT_FLAGS_READY_TIMEOUT_MS;
+        let timer;
+        const TIMED_OUT = Symbol('timeout');
+        const prefetch = this.adapter.prefetch(canonical, this.config.flagKeys !== undefined ? { flagKeys: this.config.flagKeys } : undefined);
+        try {
+            const result = await Promise.race([
+                prefetch,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+                }),
+            ]);
+            if (result === TIMED_OUT) {
+                // Fail OPEN (boot continues) but not SILENT: reads will carry STALE and
+                // the lifecycle says so. Swallow the late rejection so a slow failure
+                // does not surface as an unhandled rejection minutes later.
+                void prefetch.catch(() => undefined);
+                this.setState('STALE');
+                return;
+            }
+            this.cache = result;
+            this.setState('READY');
+        }
+        catch {
+            this.setState('STALE');
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Synchronous evaluation against the prefetched cache. Never throws —
+     * failures surface as ERROR decisions, exactly like the OpenFeature contract.
+     */
+    evaluateSync(flagKey, expectedType, defaultValue, invocationContext) {
+        if (this.state === 'SHUTDOWN') {
+            return this.errorDecision(flagKey, defaultValue, new FireweaveError('AlreadyClosed'));
+        }
+        if (this.state === 'UNINITIALIZED' || this.state === 'INITIALIZING') {
+            return this.errorDecision(flagKey, defaultValue, new FireweaveError('NotReady'));
+        }
+        if (this.state === 'ERROR') {
+            return this.errorDecision(flagKey, defaultValue, new FireweaveError('BackendUnavailable'));
+        }
+        const resolution = this.cache.get(flagKey);
+        if (resolution === undefined || resolution.found === false) {
+            // A cache miss while STALE is not a missing control point — it is an
+            // unanswered question. Reporting FLAG_NOT_FOUND there would send a caller
+            // hunting for a flag that may well exist.
+            if (this.state === 'STALE') {
+                return {
+                    flagKey,
+                    value: defaultValue,
+                    reason: 'STALE',
+                    variant: 'default',
+                    metadata: { 'fireweave.stale': true },
+                };
+            }
+            return this.errorDecision(flagKey, defaultValue, new FireweaveError('FlagNotFound'));
+        }
+        const value = resolution.value ?? null;
+        if (!matchesExpectedType(value, expectedType)) {
+            return this.errorDecision(flagKey, defaultValue, new FireweaveError('TypeMismatch'));
+        }
+        const metadata = this.metadataFor(resolution);
+        const decision = {
+            flagKey,
+            value,
+            reason: this.reasonFor(resolution),
+            ...(resolution.variant !== undefined ? { variant: resolution.variant } : {}),
+            ...(metadata !== undefined ? { metadata } : {}),
+        };
+        if (this.config.sendExposure === true) {
+            this.recordExposureFor(decision, invocationContext);
+        }
+        return decision;
+    }
+    reasonFor(resolution) {
+        if (resolution.enabled === false)
+            return 'DISABLED';
+        if (resolution.reason !== undefined)
+            return resolution.reason;
+        if (this.state === 'STALE')
+            return 'STALE';
+        return 'TARGETING_MATCH';
+    }
+    metadataFor(resolution) {
+        const metadata = {};
+        if (resolution.version !== undefined)
+            metadata['fireweave.flagVersion'] = resolution.version;
+        if (resolution.reasonCode !== undefined)
+            metadata['fireweave.reasonCode'] = resolution.reasonCode;
+        if (resolution.quotaLimited === true)
+            metadata['fireweave.quotaLimited'] = true;
+        return Object.keys(metadata).length > 0 ? metadata : undefined;
+    }
+    recordExposureFor(decision, invocationContext) {
+        if (this.adapter.recordExposure === undefined)
+            return;
+        const merged = mergeContexts(this.globalContext, invocationContext);
+        const targetingKey = typeof merged.targetingKey === 'string' ? merged.targetingKey : '';
+        if (targetingKey === '')
+            return;
+        const rc = this.releaseContext;
+        const exposure = {
+            flagKey: decision.flagKey,
+            targetingKey,
+            value: decision.value,
+            ...(decision.variant !== undefined ? { variant: decision.variant } : {}),
+            ...(rc.rolloutId !== undefined ? { rolloutId: rc.rolloutId } : {}),
+            ...(rc.changeId !== undefined ? { changeId: rc.changeId } : {}),
+            ...(rc.stampId !== undefined ? { stampId: rc.stampId } : {}),
+        };
+        this.adapter.recordExposure(exposure);
+    }
+    recordExposure(exposure) {
+        this.adapter.recordExposure?.(exposure);
+    }
+    recordSignal(signal) {
+        this.adapter.recordSignal?.(signal);
+    }
+    async registerTarget(targetingKey, options = {}) {
+        if (this.state === 'SHUTDOWN') {
+            return { ok: false, error: new FireweaveError('AlreadyClosed') };
+        }
+        if (this.adapter.registerTarget === undefined) {
+            return { ok: false, error: new FireweaveError('UnsupportedCapability') };
+        }
+        try {
+            return await this.adapter.registerTarget(targetingKey, options);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: isFireweaveError(err) ? err : new FireweaveError('BackendUnavailable'),
+            };
+        }
+    }
+    async flush(options = {}) {
+        await this.adapter.flush?.(options);
+    }
+    async shutdown() {
+        if (this.state === 'SHUTDOWN')
+            return;
+        try {
+            await this.adapter.shutdown();
+        }
+        catch {
+            // never throw from shutdown
+        }
+        this.cache = new Map();
+        this.setState('SHUTDOWN');
+    }
+    changedKeys(before, after) {
+        const keys = new Set([...before.keys(), ...after.keys()]);
+        const changed = [];
+        for (const key of keys) {
+            const a = before.get(key);
+            const b = after.get(key);
+            if (JSON.stringify(a ?? null) !== JSON.stringify(b ?? null))
+                changed.push(key);
+        }
+        return changed;
+    }
+    errorDecision(flagKey, defaultValue, err) {
+        return {
+            flagKey,
+            value: defaultValue,
+            reason: 'ERROR',
+            errorCode: err.openFeatureErrorCode,
+            errorKind: err.kind,
+            errorMessage: err.message,
+            metadata: { 'fireweave.errorKind': err.kind, ...err.metadata },
+        };
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Canonical data shapes, mirroring `spec/decision.schema.json`,
+ * `spec/signal.schema.json`, and `spec/release-context.schema.json`.
+ *
+ * Identical in meaning to the server SDK's `types.ts`. Duplicated rather than
+ * shared so the browser package has no cross-package dependency to audit; the
+ * JSON Schemas in `spec/` are what keep the two honest.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
+export type DecisionReason = 'STATIC' | 'DEFAULT' | 'TARGETING_MATCH' | 'SPLIT' | 'CACHED' | 'STALE' | 'DISABLED' | 'UNKNOWN' | 'ERROR';
+export interface Decision {
+    readonly flagKey: string;
+    readonly value: JsonValue;
+    readonly reason: DecisionReason;
+    readonly variant?: string;
+    readonly errorCode?: string;
+    readonly errorKind?: string;
+    readonly errorMessage?: string;
+    readonly metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * A browser lifecycle has one state the server does not: STALE.
+ *
+ * It means "initialize completed, but the prefetch did not, so reads are being
+ * served from an empty or outdated cache". Collapsing it into READY would make
+ * a failed boot indistinguishable from a successful one — which is the specific
+ * failure this SDK is written to avoid.
+ */
+export type LifecycleState = 'UNINITIALIZED' | 'INITIALIZING' | 'READY' | 'STALE' | 'ERROR' | 'SHUTDOWN';
+export interface CanonicalContext {
+    readonly targetingKey?: string;
+    readonly attributes: Record<string, JsonValue>;
+    readonly groups?: Record<string, string>;
+    readonly groupProperties?: Record<string, Record<string, JsonValue>>;
+}
+export type SignalKind = 'health' | 'error' | 'metric' | 'outcome';
+export interface Signal {
+    readonly kind: SignalKind;
+    readonly name: string;
+    readonly targetingKey?: string;
+    readonly flagKey?: string;
+    readonly variant?: string;
+    readonly status?: string;
+    readonly errorKind?: string;
+    readonly message?: string;
+    readonly value?: number;
+    readonly rolloutId?: string;
+    readonly changeId?: string;
+    readonly stampId?: string;
+    readonly timestamp?: string;
+}
+export interface Exposure {
+    readonly flagKey: string;
+    readonly targetingKey: string;
+    readonly value: JsonValue;
+    readonly variant?: string;
+    readonly rolloutId?: string;
+    readonly changeId?: string;
+    readonly stampId?: string;
+}
+export type ReleaseState = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED';
+export interface ReleaseContext {
+    readonly rolloutId?: string;
+    readonly changeId?: string;
+    readonly stampId?: string;
+    readonly environment?: string;
+}
+export interface Capabilities {
+    readonly static: {
+        readonly language: 'web';
+        readonly sdkVersion: string;
+        readonly specVersion: string;
+        readonly openFeature: {
+            readonly specFloor: string;
+            readonly providerName: string;
+            readonly serverOnly: boolean;
+        };
+        readonly features: Record<string, boolean>;
+    };
+    readonly runtime: {
+        readonly backend: 'fireweave' | 'inmemory' | 'none' | 'other';
+        readonly lifecycle: LifecycleState;
+        readonly features: Record<string, boolean>;
+        readonly limits: Record<string, number>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Canonical data shapes, mirroring `spec/decision.schema.json`,
+ * `spec/signal.schema.json`, and `spec/release-context.schema.json`.
+ *
+ * Identical in meaning to the server SDK's `types.ts`. Duplicated rather than
+ * shared so the browser package has no cross-package dependency to audit; the
+ * JSON Schemas in `spec/` are what keep the two honest.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@fireweaveai/web-sdk",
+  "version": "2.1.0",
+  "description": "Fireweave release-engineering SDK for browsers: control points, target registration, exposures, and health/outcome signals — with an OpenFeature web provider. Remote-only; holds no secrets.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FireWeave-HQ/fireweave-sdk.git",
+    "directory": "sdks/web/packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/sdks/web/packages/sdk#readme",
+  "bugs": "https://github.com/FireWeave-HQ/fireweave-sdk/issues",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@openfeature/web-sdk": "^1.9.0"
+  },
+  "keywords": [
+    "fireweave",
+    "release-engineering",
+    "progressive-delivery",
+    "control-points",
+    "feature-flags",
+    "openfeature",
+    "browser",
+    "web"
+  ]
+}