@fireweaveai/web-sdk-cjs 0.0.0-reserve.0

package/dist/index.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initFireweave = exports.WebControlPointsApi = exports.FireweaveWebClient = exports.DEFAULT_FLAGS_READY_TIMEOUT_MS = exports.FireweaveWebRuntime = exports.FireweaveLocalWebAdapter = exports.InMemoryWebAdapter = exports.FireweaveRemoteWebAdapter = exports.isLoopbackHostname = exports.assertNotSecretKey = exports.assertHostAllowed = exports.DEFAULT_ALLOWED_HOSTS = exports.validateInitOptions = exports.validateTargetingKey = exports.validateDefaultValue = exports.validateControlPointKey = exports.validateContext = exports.matchesExpectedType = exports.canonicalizeContext = exports.mergeContexts = exports.DEFAULT_RESERVED_ATTRIBUTE_KEYS = exports.DEFAULT_CONTEXT_LIMITS = exports.isFireweaveError = exports.ERROR_TAXONOMY = exports.FireweaveError = void 0;
+/**
+ * @fireweaveai/web-sdk — Fireweave control points for the browser (ADR-0009).
+ *
+ * Remote-only and secret-free by construction: it never evaluates locally, has
+ * no vendor SDK dependency, reads no environment, and rejects vendor/secret key
+ * shapes at the door. Credentials are passed in explicitly by the embedding app.
+ *
+ * ```ts
+ * import { initFireweave } from '@fireweaveai/web-sdk';
+ *
+ * const fw = await initFireweave({
+ *   mode: 'remote',
+ *   apiKey,
+ *   apiUrl,
+ *   context: { targetingKey: 'anonymous' },
+ * });
+ *
+ * // Reads are SYNCHRONOUS — no await, safe inside render.
+ * const on = fw.controlPoints.getBooleanValue('new-checkout', false);
+ * ```
+ *
+ * `src/` is layered domain/ · application/ · infrastructure/
+ * (test/unit/architecture-layers.test.ts guards the boundary): `domain/` is
+ * pure data + validation with no outward imports; `application/` wires
+ * domain types into the runtime/client surface, with `mode.ts` as the sole
+ * composition root allowed to reach into `infrastructure/`; `infrastructure/`
+ * holds the concrete adapters and the host allowlist.
+ */
+var errors_js_1 = require("./domain/errors.js");
+Object.defineProperty(exports, "FireweaveError", { enumerable: true, get: function () { return errors_js_1.FireweaveError; } });
+Object.defineProperty(exports, "ERROR_TAXONOMY", { enumerable: true, get: function () { return errors_js_1.ERROR_TAXONOMY; } });
+Object.defineProperty(exports, "isFireweaveError", { enumerable: true, get: function () { return errors_js_1.isFireweaveError; } });
+var context_js_1 = require("./domain/context.js");
+Object.defineProperty(exports, "DEFAULT_CONTEXT_LIMITS", { enumerable: true, get: function () { return context_js_1.DEFAULT_CONTEXT_LIMITS; } });
+Object.defineProperty(exports, "DEFAULT_RESERVED_ATTRIBUTE_KEYS", { enumerable: true, get: function () { return context_js_1.DEFAULT_RESERVED_ATTRIBUTE_KEYS; } });
+Object.defineProperty(exports, "mergeContexts", { enumerable: true, get: function () { return context_js_1.mergeContexts; } });
+var validation_js_1 = require("./domain/validation.js");
+Object.defineProperty(exports, "canonicalizeContext", { enumerable: true, get: function () { return validation_js_1.canonicalizeContext; } });
+Object.defineProperty(exports, "matchesExpectedType", { enumerable: true, get: function () { return validation_js_1.matchesExpectedType; } });
+Object.defineProperty(exports, "validateContext", { enumerable: true, get: function () { return validation_js_1.validateContext; } });
+Object.defineProperty(exports, "validateControlPointKey", { enumerable: true, get: function () { return validation_js_1.validateControlPointKey; } });
+Object.defineProperty(exports, "validateDefaultValue", { enumerable: true, get: function () { return validation_js_1.validateDefaultValue; } });
+Object.defineProperty(exports, "validateTargetingKey", { enumerable: true, get: function () { return validation_js_1.validateTargetingKey; } });
+Object.defineProperty(exports, "validateInitOptions", { enumerable: true, get: function () { return validation_js_1.validateInitOptions; } });
+var hosts_js_1 = require("./infrastructure/hosts.js");
+Object.defineProperty(exports, "DEFAULT_ALLOWED_HOSTS", { enumerable: true, get: function () { return hosts_js_1.DEFAULT_ALLOWED_HOSTS; } });
+Object.defineProperty(exports, "assertHostAllowed", { enumerable: true, get: function () { return hosts_js_1.assertHostAllowed; } });
+Object.defineProperty(exports, "assertNotSecretKey", { enumerable: true, get: function () { return hosts_js_1.assertNotSecretKey; } });
+Object.defineProperty(exports, "isLoopbackHostname", { enumerable: true, get: function () { return hosts_js_1.isLoopbackHostname; } });
+var remote_js_1 = require("./infrastructure/adapters/remote.js");
+Object.defineProperty(exports, "FireweaveRemoteWebAdapter", { enumerable: true, get: function () { return remote_js_1.FireweaveRemoteWebAdapter; } });
+var inmemory_js_1 = require("./infrastructure/adapters/inmemory.js");
+Object.defineProperty(exports, "InMemoryWebAdapter", { enumerable: true, get: function () { return inmemory_js_1.InMemoryWebAdapter; } });
+var local_js_1 = require("./infrastructure/adapters/local.js");
+Object.defineProperty(exports, "FireweaveLocalWebAdapter", { enumerable: true, get: function () { return local_js_1.FireweaveLocalWebAdapter; } });
+var runtime_js_1 = require("./application/runtime.js");
+Object.defineProperty(exports, "FireweaveWebRuntime", { enumerable: true, get: function () { return runtime_js_1.FireweaveWebRuntime; } });
+Object.defineProperty(exports, "DEFAULT_FLAGS_READY_TIMEOUT_MS", { enumerable: true, get: function () { return runtime_js_1.DEFAULT_FLAGS_READY_TIMEOUT_MS; } });
+var client_js_1 = require("./application/client.js");
+Object.defineProperty(exports, "FireweaveWebClient", { enumerable: true, get: function () { return client_js_1.FireweaveWebClient; } });
+Object.defineProperty(exports, "WebControlPointsApi", { enumerable: true, get: function () { return client_js_1.WebControlPointsApi; } });
+var mode_js_1 = require("./application/mode.js");
+Object.defineProperty(exports, "initFireweave", { enumerable: true, get: function () { return mode_js_1.initFireweave; } });

package/dist/infrastructure/adapters/inmemory.d.ts

@@ -0,0 +1,50 @@
+/**
+ * In-memory adapter — offline evaluation for tests and conformance fixtures.
+ *
+ * Declares control points up front and serves them from memory. Fault
+ * injection exists so the conformance suite can drive the error taxonomy
+ * without a network or a stub server.
+ */
+import { type FireweaveErrorKind } from '../../domain/errors.js';
+import type { AdapterResolution, AdapterRuntimeFeatures, PrefetchOptions, PrefetchResult, WebBackendAdapter } from '../../application/ports.js';
+import type { CanonicalContext, Exposure, FlagValueType, JsonValue, Signal } from '../../domain/types.js';
+export interface InMemoryFlagDefinition {
+    readonly type: FlagValueType;
+    readonly enabled: boolean;
+    readonly value: JsonValue;
+    readonly variant?: string;
+    readonly payload?: JsonValue;
+    /** Only resolve for this targeting key; otherwise the control point misses. */
+    readonly matchTargetingKey?: string;
+    readonly fireweaveReason?: AdapterResolution['reason'];
+}
+export interface InMemoryFault {
+    readonly kind: FireweaveErrorKind;
+    /** Throw on initialize rather than on prefetch. */
+    readonly onInitialize?: boolean;
+}
+export interface InMemoryWebAdapterOptions {
+    readonly flags?: Record<string, InMemoryFlagDefinition>;
+    readonly fault?: InMemoryFault;
+}
+export declare class InMemoryWebAdapter implements WebBackendAdapter {
+    readonly name: "inmemory";
+    private flags;
+    private fault;
+    private readonly exposures;
+    private readonly signals;
+    private closed;
+    constructor(options?: InMemoryWebAdapterOptions);
+    setFlags(flags: Record<string, InMemoryFlagDefinition>): void;
+    setFault(fault: InMemoryFault | undefined): void;
+    initialize(_signal?: AbortSignal): Promise<void>;
+    prefetch(context: CanonicalContext, options?: PrefetchOptions): Promise<PrefetchResult>;
+    recordExposure(exposure: Exposure): void;
+    getExposures(): readonly Exposure[];
+    recordSignal(signal: Signal): void;
+    getSignals(): readonly Signal[];
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    isClosed(): boolean;
+    features(): AdapterRuntimeFeatures;
+}

package/dist/infrastructure/adapters/inmemory.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryWebAdapter = void 0;
+/**
+ * In-memory adapter — offline evaluation for tests and conformance fixtures.
+ *
+ * Declares control points up front and serves them from memory. Fault
+ * injection exists so the conformance suite can drive the error taxonomy
+ * without a network or a stub server.
+ */
+const errors_js_1 = require("../../domain/errors.js");
+class InMemoryWebAdapter {
+    name = 'inmemory';
+    flags;
+    fault;
+    exposures = [];
+    signals = [];
+    closed = false;
+    constructor(options = {}) {
+        this.flags = new Map(Object.entries(options.flags ?? {}));
+        this.fault = options.fault;
+    }
+    setFlags(flags) {
+        this.flags = new Map(Object.entries(flags));
+    }
+    setFault(fault) {
+        this.fault = fault;
+    }
+    async initialize(_signal) {
+        if (this.fault?.onInitialize === true)
+            throw new errors_js_1.FireweaveError(this.fault.kind);
+    }
+    async prefetch(context, options) {
+        if (this.fault !== undefined && this.fault.onInitialize !== true) {
+            throw new errors_js_1.FireweaveError(this.fault.kind);
+        }
+        const wanted = options?.controlPointKeys;
+        const out = new Map();
+        for (const [key, def] of this.flags) {
+            if (wanted !== undefined && wanted.length > 0 && !wanted.includes(key))
+                continue;
+            if (def.matchTargetingKey !== undefined && context.targetingKey !== def.matchTargetingKey) {
+                out.set(key, { found: false });
+                continue;
+            }
+            const resolution = {
+                found: true,
+                enabled: def.enabled,
+                value: def.value,
+                flagType: def.type,
+            };
+            if (def.variant !== undefined)
+                resolution.variant = def.variant;
+            if (def.payload !== undefined)
+                resolution.payload = def.payload;
+            if (def.fireweaveReason !== undefined)
+                resolution.reason = def.fireweaveReason;
+            out.set(key, resolution);
+        }
+        return out;
+    }
+    recordExposure(exposure) {
+        this.exposures.push(exposure);
+    }
+    getExposures() {
+        return this.exposures;
+    }
+    recordSignal(signal) {
+        this.signals.push(signal);
+    }
+    getSignals() {
+        return this.signals;
+    }
+    async flush() {
+        // no-op: telemetry stays queryable for tests
+    }
+    async shutdown() {
+        this.closed = true;
+    }
+    isClosed() {
+        return this.closed;
+    }
+    features() {
+        return {
+            remoteEvaluation: false,
+            localEvaluation: false,
+            localOnly: true,
+            exposureEmission: true,
+            sideEffectFreeReads: true,
+            groupAnalytics: false,
+        };
+    }
+}
+exports.InMemoryWebAdapter = InMemoryWebAdapter;

package/dist/infrastructure/adapters/local.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Local development adapter for the browser — the DEV substrate of a
+ * scaffolded web harness, and the exact peer of the server SDK's
+ * `FireweaveLocalAdapter`.
+ *
+ * A key present in `devFlags` resolves with reason `STATIC`; every other key
+ * misses, which the runtime turns into the caller's own default. No network,
+ * no credentials, nothing to configure.
+ *
+ * Call-site defaults stay `false` under RAMP-1. Never write `flag(key, true)`
+ * to dogfood locally — that same `true` is the production fallback when a
+ * control point is absent from the provider, so it silently ships the ON
+ * branch. Use `devFlags`.
+ */
+import type { AdapterRuntimeFeatures, PrefetchOptions, PrefetchResult, RegisterTargetOptions, RegisterTargetResult, WebBackendAdapter } from '../../application/ports.js';
+import type { TargetKind } from '../../domain/target.js';
+import type { CanonicalContext } from '../../domain/types.js';
+export interface FireweaveLocalWebAdapterOptions {
+    readonly devFlags?: Record<string, boolean>;
+    /**
+     * Sink for the `[fireweave:local]` registerTarget trace line
+     * (spec/modes.md "registerTarget in local mode"). Defaults to
+     * `console.info`.
+     */
+    readonly log?: (message: string) => void;
+}
+/** A target recorded by {@link FireweaveLocalWebAdapter.registerTarget}. */
+export interface LocalRegisteredTarget {
+    readonly targetingKey: string;
+    readonly kind: TargetKind;
+    readonly properties: Record<string, unknown>;
+    readonly environment?: string;
+}
+export declare class FireweaveLocalWebAdapter implements WebBackendAdapter {
+    /** Not `inmemory` — that name belongs to the fixture adapter. */
+    readonly name: "other";
+    /**
+     * spec/modes.md "Behaviour per mode": local's unknown-key row is
+     * `default`/reason `DEFAULT`, not an error. This is the strict `===` seam
+     * `FireweaveWebRuntime.evaluateSync` checks on a cache miss.
+     */
+    readonly missReason: "DEFAULT";
+    private readonly devFlags;
+    private readonly log;
+    private readonly targets;
+    private closed;
+    constructor(options?: FireweaveLocalWebAdapterOptions);
+    initialize(_signal?: AbortSignal): Promise<void>;
+    /**
+     * `enabled: true` alongside `reason: 'STATIC'` is deliberate: reporting
+     * `enabled: false` for an override of `false` would make the runtime label
+     * the decision `DISABLED`, which means "exists but switched off upstream" —
+     * not what a local override expresses.
+     */
+    prefetch(_context: CanonicalContext, _options?: PrefetchOptions): Promise<PrefetchResult>;
+    /**
+     * Records the target in-process and traces it, rather than reporting
+     * `UnsupportedCapability`.
+     *
+     * The capability could instead report Unsupported so a dev harness could
+     * not *silently* look registered — but the failure being guarded against
+     * is a developer believing their targeting works because nothing objected.
+     * A recorded target plus an explicit `[fireweave:local]` line preserves
+     * that guarantee by a different route: nothing is silent, and local dev
+     * can exercise targeting rules offline instead of only in production
+     * (spec/modes.md "registerTarget in local mode").
+     *
+     * The trace names the mode, so a line appearing in a production log is
+     * itself the signal that something booted in local mode by mistake.
+     *
+     * No network call is made and nothing reaches fw-server.
+     */
+    registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
+    /** Targets recorded this process, for assertions and dev inspection. */
+    getRegisteredTargets(): readonly LocalRegisteredTarget[];
+    shutdown(): Promise<void>;
+    isClosed(): boolean;
+    features(): AdapterRuntimeFeatures;
+}

package/dist/infrastructure/adapters/local.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireweaveLocalWebAdapter = void 0;
+class FireweaveLocalWebAdapter {
+    /** Not `inmemory` — that name belongs to the fixture adapter. */
+    name = 'other';
+    /**
+     * spec/modes.md "Behaviour per mode": local's unknown-key row is
+     * `default`/reason `DEFAULT`, not an error. This is the strict `===` seam
+     * `FireweaveWebRuntime.evaluateSync` checks on a cache miss.
+     */
+    missReason = 'DEFAULT';
+    devFlags;
+    log;
+    targets = new Map();
+    closed = false;
+    constructor(options = {}) {
+        this.devFlags = { ...(options.devFlags ?? {}) };
+        this.log = options.log ?? ((m) => console.info(m));
+    }
+    async initialize(_signal) {
+        // Nothing to connect to.
+    }
+    /**
+     * `enabled: true` alongside `reason: 'STATIC'` is deliberate: reporting
+     * `enabled: false` for an override of `false` would make the runtime label
+     * the decision `DISABLED`, which means "exists but switched off upstream" —
+     * not what a local override expresses.
+     */
+    async prefetch(_context, _options) {
+        const out = new Map();
+        for (const [key, value] of Object.entries(this.devFlags)) {
+            out.set(key, {
+                found: true,
+                enabled: true,
+                value,
+                variant: value ? 'on' : 'off',
+                reason: 'STATIC',
+                flagType: 'boolean',
+            });
+        }
+        return out;
+    }
+    /**
+     * Records the target in-process and traces it, rather than reporting
+     * `UnsupportedCapability`.
+     *
+     * The capability could instead report Unsupported so a dev harness could
+     * not *silently* look registered — but the failure being guarded against
+     * is a developer believing their targeting works because nothing objected.
+     * A recorded target plus an explicit `[fireweave:local]` line preserves
+     * that guarantee by a different route: nothing is silent, and local dev
+     * can exercise targeting rules offline instead of only in production
+     * (spec/modes.md "registerTarget in local mode").
+     *
+     * The trace names the mode, so a line appearing in a production log is
+     * itself the signal that something booted in local mode by mistake.
+     *
+     * No network call is made and nothing reaches fw-server.
+     */
+    async registerTarget(targetingKey, options = {}) {
+        const kind = options.kind ?? 'user';
+        const properties = { ...(options.properties ?? {}) };
+        const target = {
+            targetingKey,
+            kind,
+            properties,
+            ...(options.environment === undefined ? {} : { environment: options.environment }),
+        };
+        this.targets.set(targetingKey, target);
+        this.log(`[fireweave:local] registerTarget ${kind} ${targetingKey} ` +
+            `${JSON.stringify(properties)} — recorded in-process, NOT sent to fw-server`);
+        return { ok: true };
+    }
+    /** Targets recorded this process, for assertions and dev inspection. */
+    getRegisteredTargets() {
+        return [...this.targets.values()];
+    }
+    async shutdown() {
+        this.closed = true;
+    }
+    isClosed() {
+        return this.closed;
+    }
+    features() {
+        return {
+            remoteEvaluation: false,
+            localEvaluation: true,
+            localOnly: true,
+            // No exposure sink exists locally; claiming otherwise would advertise
+            // emission that silently goes nowhere.
+            exposureEmission: false,
+            sideEffectFreeReads: true,
+            groupAnalytics: false,
+        };
+    }
+}
+exports.FireweaveLocalWebAdapter = FireweaveLocalWebAdapter;

package/dist/infrastructure/adapters/remote.d.ts

@@ -0,0 +1,44 @@
+import type { AdapterRuntimeFeatures, PrefetchOptions, PrefetchResult, RegisterTargetOptions, RegisterTargetResult, WebBackendAdapter } from '../../application/ports.js';
+import type { CanonicalContext, Exposure, Signal } from '../../domain/types.js';
+export type FireweaveFetchLike = typeof fetch;
+export interface FireweaveRemoteWebAdapterOptions {
+    /** fw-server base URL, e.g. `https://app-server.fireweave.ai`. */
+    readonly apiUrl: string;
+    /** Fireweave project key. Public by construction — must be scoped accordingly. */
+    readonly apiKey: string;
+    /** SSRF/misconfiguration allowlist override. `['*']` opts out. */
+    readonly allowedHosts?: readonly string[];
+    readonly requestTimeoutMs?: number;
+    /** Injected fetch (tests). Defaults to the global. */
+    readonly fetch?: FireweaveFetchLike;
+}
+export declare class FireweaveRemoteWebAdapter implements WebBackendAdapter {
+    readonly name: "fireweave";
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly allowedHosts;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    private readonly pending;
+    private ready;
+    private closed;
+    constructor(options: FireweaveRemoteWebAdapterOptions);
+    initialize(_signal?: AbortSignal): Promise<void>;
+    prefetch(context: CanonicalContext, options?: PrefetchOptions): Promise<PrefetchResult>;
+    registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
+    recordExposure(exposure: Exposure): void;
+    recordSignal(signal: Signal): void;
+    /**
+     * `beacon: true` is the unload path. It must not await anything the browser
+     * will cancel, so it uses `sendBeacon` when available and a `keepalive`
+     * fetch otherwise, and it never re-queues on failure — there is no later.
+     */
+    flush(options?: {
+        beacon?: boolean;
+    }): Promise<void>;
+    private sendBeaconOrKeepalive;
+    shutdown(): Promise<void>;
+    features(): AdapterRuntimeFeatures;
+    private toResolution;
+    private requestJson;
+}