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

package/dist/infrastructure/adapters/remote.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireweaveRemoteWebAdapter = void 0;
+/**
+ * Fireweave remote adapter for browsers — the production path.
+ *
+ * Speaks only the vendor-neutral Fireweave remote protocol to fw-server:
+ *   POST /v1/control-points/evaluate    (batch — one call per context, not per key)
+ *   POST /v1/capture
+ *   POST /v1/targets/register
+ *
+ * Auth: `Authorization: Bearer <project key>`. Never a vendor key: the
+ * constructor rejects `phc_`/`phs_`/`phx_` shapes outright (ADR-0009).
+ *
+ * Credentials are EXPLICIT constructor options. This package never reads
+ * `import.meta.env`, `process.env`, or any other ambient source — the embedding
+ * app decides what goes into its bundle, and the SDK never picks something up
+ * on its own.
+ *
+ * See spec/remote-protocol.md § Browser clients.
+ */
+const errors_js_1 = require("../../domain/errors.js");
+const hosts_js_1 = require("../hosts.js");
+const validation_js_1 = require("../../domain/validation.js");
+const EVALUATE_PATH = '/v1/control-points/evaluate';
+const CAPTURE_PATH = '/v1/capture';
+const REGISTER_TARGET_PATH = '/v1/targets/register';
+const DEFAULT_REQUEST_TIMEOUT_MS = 3_000;
+const ALLOWED_REASONS = new Set([
+    'STATIC',
+    'DEFAULT',
+    'TARGETING_MATCH',
+    'SPLIT',
+    'CACHED',
+    'STALE',
+    'DISABLED',
+    'UNKNOWN',
+    'ERROR',
+]);
+function toReason(reason) {
+    return ALLOWED_REASONS.has(reason) ? reason : undefined;
+}
+function mapHttpStatus(status) {
+    if (status === 401)
+        return new errors_js_1.FireweaveError('Authentication');
+    if (status === 403)
+        return new errors_js_1.FireweaveError('Authorization');
+    if (status === 429)
+        return new errors_js_1.FireweaveError('RateLimited');
+    return new errors_js_1.FireweaveError('BackendUnavailable');
+}
+class FireweaveRemoteWebAdapter {
+    name = 'fireweave';
+    apiUrl;
+    apiKey;
+    allowedHosts;
+    requestTimeoutMs;
+    fetchImpl;
+    pending = [];
+    ready = false;
+    closed = false;
+    constructor(options) {
+        // Validate at construction, not at first use: a misconfigured key should
+        // fail where the developer can see it, not on a user's first evaluation.
+        (0, hosts_js_1.assertNotSecretKey)(options.apiKey);
+        this.apiUrl = options.apiUrl.trim().replace(/\/+$/, '');
+        this.apiKey = options.apiKey.trim();
+        this.allowedHosts = options.allowedHosts;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async initialize(_signal) {
+        if (this.closed)
+            throw new errors_js_1.FireweaveError('AlreadyClosed');
+        if (this.apiUrl.length === 0)
+            throw new errors_js_1.FireweaveError('Configuration');
+        (0, hosts_js_1.assertHostAllowed)(this.apiUrl, this.allowedHosts);
+        this.ready = true;
+    }
+    async prefetch(context, options) {
+        if (this.closed)
+            throw new errors_js_1.FireweaveError('AlreadyClosed');
+        if (!this.ready)
+            throw new errors_js_1.FireweaveError('NotReady');
+        const targetingKeyResult = (0, validation_js_1.validateTargetingKey)(context.targetingKey, true);
+        if (!targetingKeyResult.ok)
+            throw targetingKeyResult.error;
+        const targetingKey = targetingKeyResult.value ?? '';
+        // `$`-prefixed and `fireweave.`-prefixed attributes are backend directives,
+        // not person properties, and groups travel in their own fields.
+        const attributes = {};
+        for (const [k, v] of Object.entries(context.attributes)) {
+            if (k === 'groups' || k === 'groupProperties')
+                continue;
+            if (k.startsWith('$') || k.startsWith('fireweave.'))
+                continue;
+            attributes[k] = v;
+        }
+        const body = { targetingKey };
+        if (Object.keys(attributes).length > 0)
+            body['attributes'] = attributes;
+        if (context.groups !== undefined)
+            body['groups'] = context.groups;
+        if (context.groupProperties !== undefined)
+            body['groupProperties'] = context.groupProperties;
+        if (options?.controlPointKeys !== undefined && options.controlPointKeys.length > 0) {
+            body['controlPointKeys'] = options.controlPointKeys;
+        }
+        const response = await this.requestJson(EVALUATE_PATH, body, options?.signal);
+        const out = new Map();
+        for (const item of response.decisions ?? []) {
+            out.set(item.controlPointKey, this.toResolution(item, response.quotaLimited === true));
+        }
+        return out;
+    }
+    async registerTarget(targetingKey, options = {}) {
+        if (this.closed)
+            return { ok: false, error: new errors_js_1.FireweaveError('AlreadyClosed') };
+        if (!this.ready)
+            return { ok: false, error: new errors_js_1.FireweaveError('NotReady') };
+        const targetingKeyResult = (0, validation_js_1.validateTargetingKey)(targetingKey.trim() === '' ? undefined : targetingKey, true);
+        if (!targetingKeyResult.ok)
+            return { ok: false, error: targetingKeyResult.error };
+        const body = { targetingKey };
+        if (options.kind !== undefined)
+            body['kind'] = options.kind;
+        if (options.environment !== undefined)
+            body['environment'] = options.environment;
+        if (options.properties !== undefined && Object.keys(options.properties).length > 0) {
+            body['properties'] = options.properties;
+        }
+        // Retried once, and only when the taxonomy says a retry could succeed: a
+        // rejected payload or a bad key would be rejected identically.
+        let lastError;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                await this.requestJson(REGISTER_TARGET_PATH, body, options.signal);
+                return { ok: true };
+            }
+            catch (err) {
+                lastError = err instanceof errors_js_1.FireweaveError ? err : new errors_js_1.FireweaveError('BackendUnavailable');
+                if (!lastError.retryable)
+                    break;
+            }
+        }
+        return { ok: false, ...(lastError !== undefined ? { error: lastError } : {}) };
+    }
+    recordExposure(exposure) {
+        if (this.closed || !this.ready)
+            return;
+        const event = {
+            type: 'exposure',
+            targetingKey: exposure.targetingKey,
+            controlPointKey: exposure.controlPointKey,
+            value: exposure.value,
+        };
+        if (exposure.variant !== undefined)
+            event.variant = exposure.variant;
+        if (exposure.rolloutId !== undefined)
+            event.rolloutId = exposure.rolloutId;
+        if (exposure.changeId !== undefined)
+            event.changeId = exposure.changeId;
+        if (exposure.stampId !== undefined)
+            event.stampId = exposure.stampId;
+        this.pending.push(event);
+    }
+    recordSignal(signal) {
+        if (this.closed || !this.ready)
+            return;
+        const event = {
+            type: 'signal',
+            targetingKey: signal.targetingKey ?? signal.rolloutId ?? 'fireweave-web-sdk',
+            name: signal.name,
+            properties: {
+                kind: signal.kind,
+                ...(signal.status !== undefined ? { status: signal.status } : {}),
+                ...(signal.errorKind !== undefined ? { errorKind: signal.errorKind } : {}),
+                ...(signal.message !== undefined ? { message: signal.message } : {}),
+                ...(signal.value !== undefined ? { value: signal.value } : {}),
+            },
+        };
+        if (signal.controlPointKey !== undefined)
+            event.controlPointKey = signal.controlPointKey;
+        if (signal.variant !== undefined)
+            event.variant = signal.variant;
+        if (signal.rolloutId !== undefined)
+            event.rolloutId = signal.rolloutId;
+        if (signal.timestamp !== undefined)
+            event.timestamp = signal.timestamp;
+        this.pending.push(event);
+    }
+    /**
+     * `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.
+     */
+    async flush(options = {}) {
+        if (this.closed || this.pending.length === 0)
+            return;
+        const batch = this.pending.splice(0, this.pending.length);
+        const payload = JSON.stringify({ events: batch });
+        if (options.beacon === true) {
+            this.sendBeaconOrKeepalive(payload);
+            return;
+        }
+        try {
+            await this.requestJson(CAPTURE_PATH, { events: batch });
+        }
+        catch {
+            // Never throw out of flush; re-queue so a later flush can retry.
+            this.pending.unshift(...batch);
+        }
+    }
+    sendBeaconOrKeepalive(payload) {
+        const url = `${this.apiUrl}${CAPTURE_PATH}`;
+        const nav = globalThis.navigator;
+        // sendBeacon cannot set an Authorization header, so it is only usable where
+        // the server accepts the key another way. Prefer keepalive fetch, which
+        // can, and fall back to a beacon only if fetch is unavailable.
+        try {
+            void this.fetchImpl(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${this.apiKey}` },
+                body: payload,
+                keepalive: true,
+            }).catch(() => undefined);
+            return;
+        }
+        catch {
+            // fall through to beacon
+        }
+        if (typeof nav?.sendBeacon === 'function') {
+            try {
+                nav.sendBeacon(url, new Blob([payload], { type: 'application/json' }));
+            }
+            catch {
+                // Unload-time delivery is best-effort by definition.
+            }
+        }
+    }
+    async shutdown() {
+        if (this.closed)
+            return;
+        await this.flush();
+        this.closed = true;
+        this.ready = false;
+    }
+    features() {
+        return {
+            remoteEvaluation: true,
+            // Structural, not configurable — the browser never evaluates locally.
+            localEvaluation: false,
+            localOnly: false,
+            exposureEmission: true,
+            sideEffectFreeReads: true,
+            groupAnalytics: true,
+        };
+    }
+    toResolution(item, quotaLimited) {
+        if (item.found === false) {
+            return quotaLimited ? { found: false, quotaLimited: true } : { found: false };
+        }
+        const resolution = {
+            found: true,
+            value: item.value,
+            enabled: item.enabled ?? true,
+        };
+        if (item.variant != null)
+            resolution.variant = item.variant;
+        const reason = toReason(item.reason);
+        if (reason !== undefined)
+            resolution.reason = reason;
+        if (item.payload !== undefined)
+            resolution.payload = item.payload;
+        const meta = item.controlPointMetadata ?? {};
+        if (typeof meta['fireweave.controlPointVersion'] === 'number') {
+            resolution.version = meta['fireweave.controlPointVersion'];
+        }
+        if (typeof meta['fireweave.reasonCode'] === 'string') {
+            resolution.reasonCode = meta['fireweave.reasonCode'];
+        }
+        if (quotaLimited || meta['fireweave.quotaLimited'] === true)
+            resolution.quotaLimited = true;
+        return resolution;
+    }
+    async requestJson(path, body, outerSignal) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        const onOuterAbort = () => controller.abort();
+        if (outerSignal !== undefined) {
+            if (outerSignal.aborted)
+                controller.abort();
+            else
+                outerSignal.addEventListener('abort', onOuterAbort, { once: true });
+        }
+        try {
+            let response;
+            try {
+                response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                const aborted = err instanceof Error && err.name === 'AbortError';
+                throw aborted ? new errors_js_1.FireweaveError('Timeout') : new errors_js_1.FireweaveError('Network');
+            }
+            if (response.status >= 400)
+                throw mapHttpStatus(response.status);
+            try {
+                return (await response.json());
+            }
+            catch {
+                throw new errors_js_1.FireweaveError('MalformedResponse');
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            if (outerSignal !== undefined)
+                outerSignal.removeEventListener('abort', onOuterAbort);
+        }
+    }
+}
+exports.FireweaveRemoteWebAdapter = FireweaveRemoteWebAdapter;

package/dist/infrastructure/hosts.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_ALLOWED_HOSTS: readonly string[];
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Validate a backend URL against the allowlist.
+ * Throws `FireweaveError('Configuration')` — fixed message, no host echoed,
+ * because this message can land in a shared browser console.
+ */
+export declare function assertHostAllowed(host: string, allowedHosts?: readonly string[]): void;
+/** Throw if `apiKey` looks like a vendor or secret key rather than a Fireweave project key. */
+export declare function assertNotSecretKey(apiKey: string): void;

package/dist/infrastructure/hosts.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ALLOWED_HOSTS = void 0;
+exports.isLoopbackHostname = isLoopbackHostname;
+exports.assertHostAllowed = assertHostAllowed;
+exports.assertNotSecretKey = assertNotSecretKey;
+/**
+ * Backend host allowlist — the same SSRF guard the server SDK applies, kept
+ * for a different reason.
+ *
+ * A browser cannot be tricked into reaching a cloud metadata endpoint the way a
+ * server can; the browser's own origin model already prevents that. What this
+ * guard buys here is narrower and still worth having: a mistyped or tampered
+ * `apiUrl` cannot quietly send a project key, a targeting key, and a user's
+ * evaluation attributes to an unintended host. The allowlist is ON by default,
+ * so reaching a self-hosted fw-server is a deliberate, explicit act.
+ *
+ * Scheme policy matches the server SDK: https everywhere except loopback,
+ * where plain http is allowed for local development against a dev server.
+ */
+const errors_js_1 = require("../domain/errors.js");
+exports.DEFAULT_ALLOWED_HOSTS = Object.freeze([
+    'app-server.fireweave.ai',
+    'staging-app-server.fireweave.ai',
+    'localhost',
+    '127.0.0.1',
+    '::1',
+]);
+function isLoopbackHostname(hostname) {
+    return (hostname === 'localhost' ||
+        hostname === '127.0.0.1' ||
+        hostname === '::1' ||
+        hostname === '[::1]');
+}
+/**
+ * Validate a backend URL against the allowlist.
+ * Throws `FireweaveError('Configuration')` — fixed message, no host echoed,
+ * because this message can land in a shared browser console.
+ */
+function assertHostAllowed(host, allowedHosts) {
+    let url;
+    try {
+        url = new URL(host);
+    }
+    catch {
+        throw new errors_js_1.FireweaveError('Configuration');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new errors_js_1.FireweaveError('Configuration');
+    }
+    const loopback = isLoopbackHostname(url.hostname);
+    if (url.protocol === 'http:' && !loopback) {
+        throw new errors_js_1.FireweaveError('Configuration');
+    }
+    const list = allowedHosts !== undefined && allowedHosts.length > 0 ? allowedHosts : exports.DEFAULT_ALLOWED_HOSTS;
+    if (list.includes('*'))
+        return; // explicit opt-out
+    const allowed = list.some((h) => url.hostname === h ||
+        (h === 'localhost' && loopback) ||
+        (h === '::1' && url.hostname === '[::1]'));
+    if (!allowed) {
+        throw new errors_js_1.FireweaveError('Configuration');
+    }
+}
+/**
+ * Key shapes this SDK refuses to accept.
+ *
+ * The whole security argument for a browser package (ADR-0009) is that it never
+ * wants a secret. Enforcing that at the door — rather than trusting that no
+ * code path asks for one — turns the claim into something a caller cannot
+ * accidentally violate by pasting the wrong value into their bundle config.
+ */
+const FORBIDDEN_KEY_PREFIXES = Object.freeze(['phs_', 'phx_', 'phc_']);
+/** Throw if `apiKey` looks like a vendor or secret key rather than a Fireweave project key. */
+function assertNotSecretKey(apiKey) {
+    const key = apiKey.trim();
+    if (key.length === 0)
+        throw new errors_js_1.FireweaveError('Configuration');
+    for (const prefix of FORBIDDEN_KEY_PREFIXES) {
+        if (key.startsWith(prefix)) {
+            throw new errors_js_1.FireweaveError('Configuration');
+        }
+    }
+}

package/dist/start/build-info.d.ts

@@ -0,0 +1,2 @@
+export declare const SDK_VERSION = "3.0.0";
+export declare const SDK_CHANNEL: 'staging' | 'production';

package/dist/start/build-info.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_CHANNEL = exports.SDK_VERSION = void 0;
+// GENERATED by tools/release/version.sh apply web — do not edit by hand.
+// The start profile reads SDK_CHANNEL to choose its default fw-server host
+// (docs/adr/0012-start-profile.md). test/unit/start-build-info.test.ts pins
+// SDK_VERSION to package.json, so a release that forgets to stamp fails CI.
+exports.SDK_VERSION = '3.0.0';
+exports.SDK_CHANNEL = 'production';

package/dist/start/control-points.d.ts

@@ -0,0 +1,24 @@
+export interface ControlPointDefinition {
+    /** Value served in local mode. Ignored in remote mode. */
+    readonly local: boolean;
+    /** Optional note for humans and agents. Never sent anywhere. */
+    readonly description?: string;
+}
+export type ControlPointMap = Readonly<Record<string, ControlPointDefinition>>;
+/**
+ * Validate a control-points object and return a frozen copy. Throws a TypeError naming
+ * the bad entry: the core's FireweaveError carries fixed messages only, and a
+ * typo here should say which key it was.
+ */
+export declare function normalizeControlPoints(controlPoints: unknown): ControlPointMap;
+/**
+ * Declare the app's control points. Returns its argument unchanged, typed, and
+ * checks it at import time so a typo fails where it was made.
+ *
+ *   export const controlPoints = defineControlPoints({
+ *     'new-checkout': { local: true },
+ *   });
+ */
+export declare function defineControlPoints<const T extends Record<string, ControlPointDefinition>>(controlPoints: T): T;
+/** The core local adapter's seed map. */
+export declare function toLocalControlPoints(controlPoints: ControlPointMap): Record<string, boolean>;

package/dist/start/control-points.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeControlPoints = normalizeControlPoints;
+exports.defineControlPoints = defineControlPoints;
+exports.toLocalControlPoints = toLocalControlPoints;
+/**
+ * The control-points object: every control point the app reads, with the value
+ * served in local mode. It lives in its own file
+ * (src/fireweave/control-points.ts by default) and is passed as
+ * start({ controlPoints }) — the same shape as the server SDK.
+ *
+ * It holds local values only. In remote mode fw-server and the rollout decide,
+ * and call sites keep `false` as their default (RAMP-1), so this file can
+ * never switch a feature on for real visitors.
+ */
+const index_js_1 = require("../index.js");
+/**
+ * Validate a control-points object and return a frozen copy. Throws a TypeError naming
+ * the bad entry: the core's FireweaveError carries fixed messages only, and a
+ * typo here should say which key it was.
+ */
+function normalizeControlPoints(controlPoints) {
+    if (controlPoints === undefined || controlPoints === null)
+        return Object.freeze({});
+    if (typeof controlPoints !== 'object' || Array.isArray(controlPoints)) {
+        throw new TypeError('[fireweave] start({ controlPoints }) must be an object of { key: { local: boolean } }.');
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(controlPoints)) {
+        if (!(0, index_js_1.validateControlPointKey)(key).ok)
+            throw new TypeError(`[fireweave] controlPoints: '${key}' is not a valid control point key.`);
+        if (typeof entry !== 'object' || entry === null || typeof entry.local !== 'boolean') {
+            throw new TypeError(`[fireweave] controlPoints['${key}'] must be { local: true } or { local: false }.`);
+        }
+        const { local, description } = entry;
+        if (description !== undefined && typeof description !== 'string') {
+            throw new TypeError(`[fireweave] controlPoints['${key}'].description must be a string.`);
+        }
+        out[key] = Object.freeze(description === undefined ? { local } : { local, description });
+    }
+    return Object.freeze(out);
+}
+/**
+ * Declare the app's control points. Returns its argument unchanged, typed, and
+ * checks it at import time so a typo fails where it was made.
+ *
+ *   export const controlPoints = defineControlPoints({
+ *     'new-checkout': { local: true },
+ *   });
+ */
+function defineControlPoints(controlPoints) {
+    normalizeControlPoints(controlPoints);
+    return controlPoints;
+}
+/** The core local adapter's seed map. */
+function toLocalControlPoints(controlPoints) {
+    const out = {};
+    for (const [key, entry] of Object.entries(controlPoints))
+        out[key] = entry.local;
+    return out;
+}

package/dist/start/fw.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `fw`: the page-wide accessor beside start(). Safe to import anywhere, in any
+ * order, and to destructure at module scope.
+ *
+ * Reads are synchronous (a browser renders from a prefetched cache) and never
+ * throw. Before start settles, or if it failed, they return the caller's
+ * default, and the *Details forms an ERROR decision saying why.
+ */
+import { type FireweaveWebClient, type JsonValue, type RegisterTargetResult, type TargetKind, type WebControlPointsApi } from '../index.js';
+import { type Persistence } from './identity.js';
+import { type FireweaveWebStatus, type StartState } from './state.js';
+/** The same nine read methods as the core client's controlPoints. */
+export type ControlPoints = Pick<WebControlPointsApi, 'evaluate' | 'getBooleanValue' | 'getStringValue' | 'getNumberValue' | 'getObjectValue' | 'getBooleanDetails' | 'getStringDetails' | 'getNumberDetails' | 'getObjectDetails'>;
+export interface IdentifyOptions {
+    /** Defaults to 'user'. */
+    readonly kind?: TargetKind;
+}
+export interface FireweaveWebStart {
+    /** Read control points: `fw.controlPoints.getBooleanValue('key', false)`. Synchronous. */
+    readonly controlPoints: ControlPoints;
+    /** Sign-in and session restore: register the user, then switch decisions to their key. Never throws. */
+    identify(targetingKey: string, properties?: Record<string, JsonValue>, options?: IdentifyOptions): Promise<RegisterTargetResult>;
+    /** Sign-out: back to this browser's device id. Never throws. */
+    reset(): Promise<void>;
+    /** The anonymous key, for joining with analytics. Undefined before start. */
+    deviceId(): string | undefined;
+    /** Change storage at runtime, for consent: 'memory' deletes what was stored. */
+    setPersistence(mode: Persistence): void;
+    /** Withdraw consent and start over: clears storage and mints a fresh in-memory device id. */
+    forget(): Promise<void>;
+    /** Settles when the current start attempt does. Never rejects; already resolved when nothing is starting. */
+    readonly ready: Promise<void>;
+    /** What start() decided and how it went: mode, channel, host, key source, problem. Never the key. */
+    status(): FireweaveWebStatus;
+    /** Called on every state change, including the re-prefetch after identify or reset. Returns unsubscribe. */
+    subscribe(listener: (state: StartState) => void): () => void;
+    /** The core client, for anything the facade does not cover. Undefined until start settles. */
+    client(): FireweaveWebClient | undefined;
+    /** Flush and close. A later start() begins fresh. */
+    shutdown(): Promise<void>;
+}
+export declare const fw: FireweaveWebStart;