@fireweaveai/web-sdk 2.1.0 → 2.1.1-staging.2

package/README.md

@@ -0,0 +1,105 @@
+# @fireweaveai/web-sdk (Web SDK)
+
+Fireweave control points for the browser ([ADR-0009](../../docs/adr/0009-browser-control-points.md)) —
+**control points** and **target registration**, the two v1 capabilities
+([spec/control-points.md](../../spec/control-points.md) "Scope of v1"; spec v0.1.0).
+
+- **Remote-only and secret-free by construction.** No local evaluation, no vendor SDK dependency, no environment reads, and vendor/secret key shapes are rejected at the door.
+- **Reads are synchronous** — `controlPoints.getBooleanValue(...)` returns a value directly, no `await`, safe inside a render path. `initFireweave` prefetches a decision cache once per context; reads afterward are a pure in-memory lookup.
+- **Bun is the toolchain.** Tested on Bun only — this package ships no server entry point, reads no environment, and imports no runtime built-ins, so Node/Deno are not target runtimes for it.
+
+## Install
+
+```bash
+bun add @fireweaveai/web-sdk   # or: npm install @fireweaveai/web-sdk
+```
+
+## Quick start (production path)
+
+```ts
+import { initFireweave } from '@fireweaveai/web-sdk';
+
+// apiKey/apiUrl are required, explicit options — the SDK reads no
+// environment variables (spec/modes.md). The apiKey is a Fireweave PROJECT
+// key, public by construction (ADR-0009) — never a secret.
+const fireweave = await initFireweave({
+  mode: 'remote',
+  apiKey: PUBLIC_FW_PROJECT_API_KEY,
+  apiUrl: PUBLIC_FW_API_URL,
+  context: { targetingKey: 'anonymous' },
+});
+
+// Reads are SYNCHRONOUS — no await, safe inside render.
+const enabled = fireweave.controlPoints.getBooleanValue('new-checkout', false);
+
+// At sign-in: register durable targeting facts, then re-prefetch under that id.
+await fireweave.identify('user_42', { kind: 'user', properties: { plan: 'pro' } });
+
+await fireweave.shutdown();
+```
+
+## Quick start (offline, local mode)
+
+```ts
+import { initFireweave } from '@fireweaveai/web-sdk';
+
+const fireweave = await initFireweave({
+  mode: 'local',
+  local: { controlPoints: { 'new-checkout': true } },
+});
+
+// → true
+fireweave.controlPoints.getBooleanValue('new-checkout', false);
+
+await fireweave.shutdown();
+```
+
+`initFireweave` is the single entry point (spec/modes.md): `mode` is required and never inferred.
+A bad host or missing credential still fails loudly at `initFireweave()` even though
+`FireweaveWebRuntime.initialize()` itself is deliberately fail-open — a hung or failing prefetch
+must not block app boot ([ADR-0009](../../docs/adr/0009-browser-control-points.md) "Fail-open, not
+fail-silent"). When the initial prefetch race loses to its ceiling, the runtime serves defaults
+with reason `STALE` rather than blocking.
+
+## Module layout
+
+| Module | Responsibility |
+| --- | --- |
+| `application/runtime.ts` | `FireweaveWebRuntime` — prefetch-once-per-context cache, lifecycle state, sync reads. |
+| `application/client.ts` | `FireweaveWebClient` — `controlPoints`, `registerTarget`, `identify`. |
+| `application/mode.ts` | `initFireweave` — the single entry point; the only module allowed to import concrete adapters. |
+| `infrastructure/adapters/remote.ts` | `FireweaveRemoteWebAdapter` — the production backend (`/v1/flags/evaluate`, `/v1/targets/register`). |
+| `infrastructure/adapters/inmemory.ts` | Deterministic fixture-driven adapter for tests and conformance. |
+| `infrastructure/adapters/local.ts` | `FireweaveLocalWebAdapter` — the DEV substrate `initFireweave({ mode: 'local' })` builds. |
+| `application/ports.ts` | The `WebBackendAdapter` boundary. |
+| `domain/context.ts` | Merge order, deep copy, bounds, reserved keys. |
+| `domain/errors.ts` | The 15-kind error taxonomy. |
+| `infrastructure/hosts.ts` | SSRF allowlist + secret-key-shape rejection (on by default; https required off-loopback). |
+
+## Configuration
+
+The SDK reads no environment variables — every option is an explicit argument to `initFireweave`.
+
+| Option | Mode | Description |
+| --- | --- | --- |
+| `apiUrl` | `remote` | fw-server base URL (required) |
+| `apiKey` | `remote` | Fireweave **project** key — public by construction, never a secret (required) |
+| `allowedHosts` | `remote` | SSRF allowlist override; defaults to the `apiUrl` host plus loopback |
+| `context` | both | initial evaluation context (e.g. an anonymous `targetingKey`) to prefetch under |
+| `local.controlPoints` | `local` | seeded boolean overrides; a present key resolves `STATIC`, an absent key misses to the caller's default with reason `DEFAULT` |
+
+## Development
+
+```bash
+bun install          # from sdks/web
+bun run build        # emit dist/ (package exports resolve to it)
+bun run verify        # typecheck + test + conformance
+```
+
+## Documentation
+
+Full docs live in [`docs/`](../../docs/), and [ADR-0009](../../docs/adr/0009-browser-control-points.md) records the browser-specific design (fail-open prefetch, secret-key rejection, sync reads).
+
+## License
+
+[MIT](../../LICENSE).

package/dist/application/client.d.ts

@@ -0,0 +1,120 @@
+/**
+ * FireweaveWebClient — the Fireweave-native surface, mirroring the server
+ * SDK's `FireweaveClient` namespace for namespace (ADR-0003: extensions live
+ * beside the OpenFeature client, never inside it).
+ *
+ * Scope of v1 (spec/control-points.md "Scope of v1"): exactly two
+ * capabilities — control points and target registration. Releases,
+ * exposures, signals, capabilities discovery and guardrails are out of v1;
+ * this client MUST NOT expose them (conformance/surface/control-points.surface.json
+ * "mustNotExpose"). The dynamic `invokeCapability` dispatcher and the
+ * deprecated `flags` alias survive unchanged.
+ *
+ * One divergence from the server SDK, and it is intentional: `controlPoints.*`
+ * is SYNCHRONOUS here and promise-returning on the server. That follows from
+ * the OpenFeature web contract — browser reads happen in render paths — and
+ * is recorded in docs/compatibility.md as a surface difference rather than a
+ * gap.
+ */
+import { FireweaveError } from '../domain/errors.js';
+import type { ContextInput } from '../domain/context.js';
+import type { FireweaveWebRuntime, ExpectedFlagType } from './runtime.js';
+import type { Decision, JsonValue } from '../domain/types.js';
+import type { RegisterTargetOptions, RegisterTargetResult } from './ports.js';
+export interface ExtensionResult {
+    readonly ok: boolean;
+    readonly error?: FireweaveError;
+    readonly degraded?: boolean;
+}
+/**
+ * Reserved for cross-language surface parity
+ * (conformance/surface/control-points.surface.json pins `evaluate(key, type,
+ * default, context?, options?)` across every language). Currently INERT on
+ * web — accepted and typed, nothing reads it.
+ *
+ * Node's `EvaluateOptions` carries `signal` (abort an in-flight network
+ * call), `includePayload` (attach raw flag payload metadata), and
+ * `sendExposure` (opt into exposure emission for this one call). None of
+ * those map cleanly onto web's contract: `evaluate` here is a SYNCHRONOUS
+ * read of an already-prefetched cache (ADR-0009), so there is no in-flight
+ * I/O to abort at read time, and exposure emission is a constructor-level
+ * opt-in (`FireweaveWebRuntimeConfig.sendExposure`) rather than a per-call
+ * one. The parameter exists so this method's ARITY matches the descriptor
+ * every language is pinned to, not because it does anything yet.
+ */
+export interface EvaluateOptions {
+}
+/**
+ * Control-point evaluation on the public client surface — decision-returning,
+ * without reaching into the runtime. Never throws; errors surface as ERROR
+ * decisions, exactly like the OpenFeature path.
+ */
+export declare class WebControlPointsApi {
+    private readonly runtime;
+    constructor(runtime: FireweaveWebRuntime);
+    evaluate(flagKey: string, expectedType: ExpectedFlagType, defaultValue: JsonValue, context?: ContextInput, _options?: EvaluateOptions): Decision;
+    getBooleanValue(flagKey: string, defaultValue: boolean, context?: ContextInput): boolean;
+    getStringValue(flagKey: string, defaultValue: string, context?: ContextInput): string;
+    getNumberValue(flagKey: string, defaultValue: number, context?: ContextInput): number;
+    getObjectValue(flagKey: string, defaultValue: JsonValue, context?: ContextInput): JsonValue;
+    /**
+     * Detailed reads — the whole {@link Decision} rather than just its value.
+     *
+     * Same arguments as the `*Value` pair above, so a caller upgrades from one
+     * to the other without restructuring the call (spec/control-points.md "The
+     * nine methods"). SYNCHRONOUS like every other read here (ADR-0009).
+     */
+    getBooleanDetails(flagKey: string, defaultValue: boolean, context?: ContextInput): Decision;
+    getStringDetails(flagKey: string, defaultValue: string, context?: ContextInput): Decision;
+    getNumberDetails(flagKey: string, defaultValue: number, context?: ContextInput): Decision;
+    getObjectDetails(flagKey: string, defaultValue: JsonValue, context?: ContextInput): Decision;
+}
+export interface FireweaveWebClientOptions {
+}
+export declare class FireweaveWebClient {
+    readonly runtime: FireweaveWebRuntime;
+    readonly controlPoints: WebControlPointsApi;
+    /**
+     * Control-point evaluation under its former name.
+     *
+     * @deprecated Renamed to {@link FireweaveWebClient.controlPoints}
+     * (ADR-0007). Identical and fully supported —
+     * `client.flags === client.controlPoints` — so no migration is required and
+     * none is planned. Silent at runtime: the alias is permanent, not scheduled
+     * for removal, so there is nothing to warn a caller toward — deprecation is
+     * conveyed by this doc comment only (no log, and no env gate to control
+     * one, since the SDK reads no environment variables regardless — ADR-0009
+     * security rule 3).
+     */
+    get flags(): WebControlPointsApi;
+    constructor(runtime: FireweaveWebRuntime, _options?: FireweaveWebClientOptions);
+    /**
+     * Dynamic capability dispatch. Unknown capabilities — currently all of
+     * them, v1's SUPPORTED_CAPABILITIES is empty — degrade with
+     * UnsupportedCapability, never throw. Any future capability listed in
+     * SUPPORTED_CAPABILITIES is lifecycle-gated the same way (ruling 17).
+     */
+    invokeCapability(capability: string, _args?: Record<string, JsonValue>): ExtensionResult;
+    initialize(context?: ContextInput): Promise<void>;
+    /**
+     * Register durable targeting facts for a target (spec/modes.md).
+     *
+     * Resolves rather than throwing: this runs in sign-in paths, where a
+     * targeting concern must not break authentication. In local mode this
+     * records in-process and traces the call; nothing reaches fw-server (see
+     * `FireweaveLocalWebAdapter.registerTarget`).
+     */
+    registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
+    /**
+     * Sign-in hook: register the user's durable targeting properties, then
+     * re-prefetch under that id so percentage ramps bucket on a stable key.
+     *
+     * Two kinds of property feed a rule and both are needed — DURABLE ones
+     * registered here, and PER-REQUEST ones carried in the evaluation context. A
+     * rule targeting a property that is never registered AND never sent matches
+     * nobody, silently.
+     */
+    identify(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/application/client.d.ts.map

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

package/dist/application/client.js

@@ -0,0 +1,160 @@
+/**
+ * FireweaveWebClient — the Fireweave-native surface, mirroring the server
+ * SDK's `FireweaveClient` namespace for namespace (ADR-0003: extensions live
+ * beside the OpenFeature client, never inside it).
+ *
+ * Scope of v1 (spec/control-points.md "Scope of v1"): exactly two
+ * capabilities — control points and target registration. Releases,
+ * exposures, signals, capabilities discovery and guardrails are out of v1;
+ * this client MUST NOT expose them (conformance/surface/control-points.surface.json
+ * "mustNotExpose"). The dynamic `invokeCapability` dispatcher and the
+ * deprecated `flags` alias survive unchanged.
+ *
+ * One divergence from the server SDK, and it is intentional: `controlPoints.*`
+ * is SYNCHRONOUS here and promise-returning on the server. That follows from
+ * the OpenFeature web contract — browser reads happen in render paths — and
+ * is recorded in docs/compatibility.md as a surface difference rather than a
+ * gap.
+ */
+import { FireweaveError } from '../domain/errors.js';
+function failure(error, degraded = false) {
+    return degraded ? { ok: false, error, degraded: true } : { ok: false, error };
+}
+/**
+ * Lifecycle gate for extension calls. Kept for forward compatibility with
+ * `invokeCapability` (ruling 17, Go/Java model) even though v1's
+ * SUPPORTED_CAPABILITIES is empty and therefore never reaches it today — a
+ * future capability re-added to the allowlist is gated the same way without
+ * this function needing to be reinvented.
+ */
+function lifecycleGate(runtime) {
+    const state = runtime.getState();
+    if (state === 'SHUTDOWN')
+        return new FireweaveError('AlreadyClosed');
+    if (state === 'UNINITIALIZED' || state === 'INITIALIZING')
+        return new FireweaveError('NotReady');
+    return undefined;
+}
+/**
+ * Control-point evaluation on the public client surface — decision-returning,
+ * without reaching into the runtime. Never throws; errors surface as ERROR
+ * decisions, exactly like the OpenFeature path.
+ */
+export class WebControlPointsApi {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    evaluate(flagKey, expectedType, defaultValue, context, _options) {
+        return this.runtime.evaluateSync(flagKey, expectedType, defaultValue, context);
+    }
+    getBooleanValue(flagKey, defaultValue, context) {
+        return this.evaluate(flagKey, 'boolean', defaultValue, context).value;
+    }
+    getStringValue(flagKey, defaultValue, context) {
+        return this.evaluate(flagKey, 'string', defaultValue, context).value;
+    }
+    getNumberValue(flagKey, defaultValue, context) {
+        return this.evaluate(flagKey, 'number', defaultValue, context).value;
+    }
+    getObjectValue(flagKey, defaultValue, context) {
+        return this.evaluate(flagKey, 'object', defaultValue, context).value;
+    }
+    /**
+     * Detailed reads — the whole {@link Decision} rather than just its value.
+     *
+     * Same arguments as the `*Value` pair above, so a caller upgrades from one
+     * to the other without restructuring the call (spec/control-points.md "The
+     * nine methods"). SYNCHRONOUS like every other read here (ADR-0009).
+     */
+    getBooleanDetails(flagKey, defaultValue, context) {
+        return this.evaluate(flagKey, 'boolean', defaultValue, context);
+    }
+    getStringDetails(flagKey, defaultValue, context) {
+        return this.evaluate(flagKey, 'string', defaultValue, context);
+    }
+    getNumberDetails(flagKey, defaultValue, context) {
+        return this.evaluate(flagKey, 'number', defaultValue, context);
+    }
+    getObjectDetails(flagKey, defaultValue, context) {
+        return this.evaluate(flagKey, 'object', defaultValue, context);
+    }
+}
+/**
+ * Names invokeCapability will dispatch instead of degrading with
+ * UnsupportedCapability. Empty in v1: releases, exposures, signals,
+ * capabilities discovery, and guardrails are all out of scope
+ * (spec/control-points.md) and MUST NOT be exposed, so a cut namespace's
+ * capability string resolves exactly like any other unknown string.
+ */
+const SUPPORTED_CAPABILITIES = Object.freeze([]);
+export class FireweaveWebClient {
+    runtime;
+    controlPoints;
+    /**
+     * Control-point evaluation under its former name.
+     *
+     * @deprecated Renamed to {@link FireweaveWebClient.controlPoints}
+     * (ADR-0007). Identical and fully supported —
+     * `client.flags === client.controlPoints` — so no migration is required and
+     * none is planned. Silent at runtime: the alias is permanent, not scheduled
+     * for removal, so there is nothing to warn a caller toward — deprecation is
+     * conveyed by this doc comment only (no log, and no env gate to control
+     * one, since the SDK reads no environment variables regardless — ADR-0009
+     * security rule 3).
+     */
+    get flags() {
+        return this.controlPoints;
+    }
+    constructor(runtime, _options = {}) {
+        this.runtime = runtime;
+        this.controlPoints = new WebControlPointsApi(runtime);
+    }
+    /**
+     * Dynamic capability dispatch. Unknown capabilities — currently all of
+     * them, v1's SUPPORTED_CAPABILITIES is empty — degrade with
+     * UnsupportedCapability, never throw. Any future capability listed in
+     * SUPPORTED_CAPABILITIES is lifecycle-gated the same way (ruling 17).
+     */
+    invokeCapability(capability, _args) {
+        if (!SUPPORTED_CAPABILITIES.includes(capability)) {
+            return failure(new FireweaveError('UnsupportedCapability'), true);
+        }
+        const gate = lifecycleGate(this.runtime);
+        if (gate !== undefined)
+            return failure(gate, true);
+        return { ok: true };
+    }
+    initialize(context) {
+        return this.runtime.initialize(context);
+    }
+    /**
+     * Register durable targeting facts for a target (spec/modes.md).
+     *
+     * Resolves rather than throwing: this runs in sign-in paths, where a
+     * targeting concern must not break authentication. In local mode this
+     * records in-process and traces the call; nothing reaches fw-server (see
+     * `FireweaveLocalWebAdapter.registerTarget`).
+     */
+    registerTarget(targetingKey, options = {}) {
+        return this.runtime.registerTarget(targetingKey, options);
+    }
+    /**
+     * Sign-in hook: register the user's durable targeting properties, then
+     * re-prefetch under that id so percentage ramps bucket on a stable key.
+     *
+     * Two kinds of property feed a rule and both are needed — DURABLE ones
+     * registered here, and PER-REQUEST ones carried in the evaluation context. A
+     * rule targeting a property that is never registered AND never sent matches
+     * nobody, silently.
+     */
+    async identify(targetingKey, options = {}) {
+        const result = await this.runtime.registerTarget(targetingKey, options);
+        await this.runtime.setContext({ targetingKey });
+        return result;
+    }
+    async shutdown() {
+        await this.runtime.shutdown();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/application/client.js.map

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

package/dist/application/mode.d.ts

@@ -0,0 +1,100 @@
+/**
+ * initFireweave — the single SDK entry point (spec/modes.md).
+ *
+ * `mode` is required and never inferred: a missing or mistyped credential
+ * must fail loudly at boot, not silently fall back to local evaluation —
+ * that failure mode looks like a green boot and a feature that never ramps.
+ * This function's only job is to validate the initialisation-time contract
+ * and select the matching adapter; nothing downstream branches on mode again
+ * (spec/modes.md "Behaviour per mode" — both adapters implement the same
+ * WebBackendAdapter port, so FireweaveWebClient / FireweaveWebRuntime stay
+ * mode-blind).
+ *
+ * Initialisation fails loudly (throws); reads on the returned client never do
+ * (spec/control-points.md "initialise is the exception").
+ *
+ * ## A web-specific wrinkle: `FireweaveWebRuntime.initialize()` never throws
+ *
+ * Node's `FireweaveRuntime.initialize()` rejects on adapter failure, so
+ * node's initFireweave can just `await runtime.initialize()` and let a bad
+ * host/credential propagate. Web's runtime is deliberately fail-OPEN at
+ * `initialize()` — a hung or failing prefetch must not block app boot
+ * (ADR-0009 "Fail-open, not fail-silent"), so it swallows adapter failures
+ * into ERROR/STALE state instead of rejecting.
+ *
+ * That non-throwing contract is correct for TRANSIENT failures (the network
+ * happened to be down) but wrong for the four Configuration rows below,
+ * which spec/modes.md requires to fail loudly at boot. This module closes
+ * that gap itself in two parts: `validateInitOptions` (domain/validation.ts)
+ * covers rows 1/2/4 (mode absent/unrecognised, remote apiKey/apiUrl blank,
+ * local combined with credentials) exactly like node's `initFireweave` does;
+ * `initRemote` covers row 3 (the host allowlist) with a direct, SYNCHRONOUS
+ * `assertHostAllowed` call, before ever calling into the runtime — that call
+ * is what makes a bad host fail LOUDLY here, because the runtime itself
+ * deliberately never throws. A genuinely transient prefetch failure (host is
+ * fine, network hiccups) still resolves into ERROR/STALE rather than
+ * throwing — that fail-open behaviour is unchanged and is not one of the
+ * four rows.
+ */
+import { FireweaveWebClient } from './client.js';
+import type { FireweaveFetchLike } from '../infrastructure/adapters/remote.js';
+import type { ContextInput } from '../domain/context.js';
+export interface InitFireweaveRemoteOptions {
+    /** Evaluate against fw-server over the network (spec/remote-protocol.md). */
+    readonly mode: 'remote';
+    /** Fireweave project key. Public by construction (ADR-0009) — required, never read from the environment. */
+    readonly apiKey: string;
+    /** fw-server base URL. Required — never read from the environment. */
+    readonly apiUrl: string;
+    /**
+     * SSRF/misconfiguration allowlist override (spec/modes.md "apiUrl fails
+     * the host allowlist"). Default: the canonical Fireweave hosts + loopback
+     * (`DEFAULT_ALLOWED_HOSTS`). A self-hosted fw-server must list its own
+     * host explicitly; `['*']` opts out.
+     */
+    readonly allowedHosts?: readonly string[];
+    /** Injected fetch (tests). Production uses the runtime's global `fetch`. */
+    readonly fetch?: FireweaveFetchLike;
+    /** Initial evaluation context (e.g. an anonymous targetingKey) to prefetch under. */
+    readonly context?: ContextInput;
+}
+export interface InitFireweaveLocalOptions {
+    /** Evaluate against an in-process seeded map; no network (spec/modes.md). */
+    readonly mode: 'local';
+    readonly local?: {
+        /**
+         * Per-key boolean overrides — the seeded local map. A present key
+         * resolves with reason `STATIC`; an absent key misses so the caller's
+         * own default is used. May be empty or omitted entirely.
+         */
+        readonly controlPoints?: 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;
+    };
+    /** Initial evaluation context (e.g. an anonymous targetingKey) to prefetch under. */
+    readonly context?: ContextInput;
+}
+export type InitFireweaveOptions = InitFireweaveRemoteOptions | InitFireweaveLocalOptions;
+/**
+ * Build the adapter matching `options.mode` and bring a
+ * {@link FireweaveWebClient} up.
+ *
+ * Throws {@link FireweaveError} (kind `Configuration`) for every row of the
+ * initialisation-validation table (spec/modes.md):
+ *  - `mode` absent or unrecognised
+ *  - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
+ *  - `apiUrl` fails the host allowlist
+ *  - `mode: 'local'` with credentials supplied
+ *
+ * The first, second and fourth rows are `validateInitOptions`'s job
+ * (domain/validation.ts, shared discipline with node's `initFireweave`); the
+ * third is validated downstream, inside `initRemote`, for the reason the
+ * module doc comment explains — `FireweaveWebRuntime.initialize()` itself
+ * never throws.
+ */
+export declare function initFireweave(options: InitFireweaveOptions): Promise<FireweaveWebClient>;
+//# sourceMappingURL=mode.d.ts.map

package/dist/application/mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/application/mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAG/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,4GAA4G;IAC5G,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf;;;;WAIG;QACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjD;;;;WAIG;QACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;KAC1C,CAAC;IACF,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;CACjC;AAED,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,GAAG,yBAAyB,CAAC;AAmC1F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAK9F"}

package/dist/application/mode.js

@@ -0,0 +1,99 @@
+/**
+ * initFireweave — the single SDK entry point (spec/modes.md).
+ *
+ * `mode` is required and never inferred: a missing or mistyped credential
+ * must fail loudly at boot, not silently fall back to local evaluation —
+ * that failure mode looks like a green boot and a feature that never ramps.
+ * This function's only job is to validate the initialisation-time contract
+ * and select the matching adapter; nothing downstream branches on mode again
+ * (spec/modes.md "Behaviour per mode" — both adapters implement the same
+ * WebBackendAdapter port, so FireweaveWebClient / FireweaveWebRuntime stay
+ * mode-blind).
+ *
+ * Initialisation fails loudly (throws); reads on the returned client never do
+ * (spec/control-points.md "initialise is the exception").
+ *
+ * ## A web-specific wrinkle: `FireweaveWebRuntime.initialize()` never throws
+ *
+ * Node's `FireweaveRuntime.initialize()` rejects on adapter failure, so
+ * node's initFireweave can just `await runtime.initialize()` and let a bad
+ * host/credential propagate. Web's runtime is deliberately fail-OPEN at
+ * `initialize()` — a hung or failing prefetch must not block app boot
+ * (ADR-0009 "Fail-open, not fail-silent"), so it swallows adapter failures
+ * into ERROR/STALE state instead of rejecting.
+ *
+ * That non-throwing contract is correct for TRANSIENT failures (the network
+ * happened to be down) but wrong for the four Configuration rows below,
+ * which spec/modes.md requires to fail loudly at boot. This module closes
+ * that gap itself in two parts: `validateInitOptions` (domain/validation.ts)
+ * covers rows 1/2/4 (mode absent/unrecognised, remote apiKey/apiUrl blank,
+ * local combined with credentials) exactly like node's `initFireweave` does;
+ * `initRemote` covers row 3 (the host allowlist) with a direct, SYNCHRONOUS
+ * `assertHostAllowed` call, before ever calling into the runtime — that call
+ * is what makes a bad host fail LOUDLY here, because the runtime itself
+ * deliberately never throws. A genuinely transient prefetch failure (host is
+ * fine, network hiccups) still resolves into ERROR/STALE rather than
+ * throwing — that fail-open behaviour is unchanged and is not one of the
+ * four rows.
+ */
+import { FireweaveWebClient } from './client.js';
+import { FireweaveWebRuntime } from './runtime.js';
+import { FireweaveLocalWebAdapter } from '../infrastructure/adapters/local.js';
+import { FireweaveRemoteWebAdapter } from '../infrastructure/adapters/remote.js';
+import { assertHostAllowed } from '../infrastructure/hosts.js';
+import { validateInitOptions } from '../domain/validation.js';
+async function initLocal(options) {
+    const local = options.local ?? {};
+    const adapter = new FireweaveLocalWebAdapter({
+        devFlags: local.controlPoints ?? {},
+        ...(local.log !== undefined ? { log: local.log } : {}),
+    });
+    const runtime = new FireweaveWebRuntime(adapter);
+    const client = new FireweaveWebClient(runtime);
+    await client.initialize(options.context);
+    return client;
+}
+async function initRemote(options) {
+    const { apiKey, apiUrl, allowedHosts, fetch } = options;
+    // `validateInitOptions` (called by `initFireweave`, below) has already
+    // ruled out blank apiKey/apiUrl by the time this runs — only the host
+    // allowlist row remains to check here. See the module doc comment: this
+    // call — not runtime.initialize() — is what makes a bad host fail LOUDLY
+    // here, because the runtime itself deliberately never throws.
+    assertHostAllowed(apiUrl, allowedHosts);
+    const adapter = new FireweaveRemoteWebAdapter({
+        apiUrl,
+        apiKey,
+        ...(allowedHosts !== undefined ? { allowedHosts } : {}),
+        ...(fetch !== undefined ? { fetch } : {}),
+    });
+    const runtime = new FireweaveWebRuntime(adapter);
+    const client = new FireweaveWebClient(runtime);
+    await client.initialize(options.context);
+    return client;
+}
+/**
+ * Build the adapter matching `options.mode` and bring a
+ * {@link FireweaveWebClient} up.
+ *
+ * Throws {@link FireweaveError} (kind `Configuration`) for every row of the
+ * initialisation-validation table (spec/modes.md):
+ *  - `mode` absent or unrecognised
+ *  - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
+ *  - `apiUrl` fails the host allowlist
+ *  - `mode: 'local'` with credentials supplied
+ *
+ * The first, second and fourth rows are `validateInitOptions`'s job
+ * (domain/validation.ts, shared discipline with node's `initFireweave`); the
+ * third is validated downstream, inside `initRemote`, for the reason the
+ * module doc comment explains — `FireweaveWebRuntime.initialize()` itself
+ * never throws.
+ */
+export async function initFireweave(options) {
+    const validated = validateInitOptions(options);
+    if (!validated.ok)
+        throw validated.error;
+    const validOptions = validated.value;
+    return validOptions.mode === 'local' ? initLocal(validOptions) : initRemote(validOptions);
+}
+//# sourceMappingURL=mode.js.map

package/dist/application/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../src/application/mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AA8C9D,KAAK,UAAU,SAAS,CAAC,OAAkC;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,wBAAwB,CAAC;QAC3C,QAAQ,EAAE,KAAK,CAAC,aAAa,IAAI,EAAE;QACnC,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvD,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,OAAmC;IAC3D,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IACxD,uEAAuE;IACvE,sEAAsE;IACtE,wEAAwE;IACxE,yEAAyE;IACzE,8DAA8D;IAC9D,iBAAiB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAExC,MAAM,OAAO,GAAG,IAAI,yBAAyB,CAAC;QAC5C,MAAM;QACN,MAAM;QACN,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1C,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA6B;IAC/D,MAAM,SAAS,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,CAAC,SAAS,CAAC,EAAE;QAAE,MAAM,SAAS,CAAC,KAAK,CAAC;IACzC,MAAM,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC;IACrC,OAAO,YAAY,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAC5F,CAAC"}

package/dist/{adapter.d.ts → application/ports.d.ts}

@@ -14,8 +14,9 @@
  * Adapters translate canonical requests to the Fireweave remote protocol; they
  * never see OpenFeature types.
  */
-import type { CanonicalContext, DecisionReason, Exposure, FlagValueType, JsonValue, Signal } from './types.js';
-import type { FireweaveError } from './errors.js';
+import type { CanonicalContext, DecisionReason, Exposure, FlagValueType, JsonValue, Signal } from '../domain/types.js';
+import type { FireweaveError } from '../domain/errors.js';
+import type { TargetKind } from '../domain/target.js';
 export interface AdapterResolution {
     found: boolean;
     enabled?: boolean;
@@ -35,7 +36,6 @@ export interface PrefetchOptions {
     readonly flagKeys?: readonly string[];
     readonly signal?: AbortSignal;
 }
-export type TargetKind = 'user' | 'device';
 export interface RegisterTargetOptions {
     readonly kind?: TargetKind;
     readonly properties?: Record<string, JsonValue>;
@@ -63,6 +63,21 @@ export interface AdapterRuntimeFeatures {
 }
 export interface WebBackendAdapter {
     readonly name: 'fireweave' | 'inmemory' | 'other';
+    /**
+     * Miss-reason override for a control point ABSENT from the prefetch result
+     * (spec/modes.md "Behaviour per mode": local mode's unknown-key row is
+     * `default`/reason `DEFAULT`, not an error — unlike remote's
+     * `default`/`ERROR`/`FlagNotFound`).
+     *
+     * Node's per-call `resolve()` lets a miss carry its own `reason: 'DEFAULT'`
+     * on the resolution object itself. Web's adapter returns EVERY decision for
+     * a context in one batch (`prefetch`), so there is no per-key resolution
+     * object for a key that was never in the batch at all — the seam instead
+     * lives on the adapter. `FireweaveLocalWebAdapter` sets this to `'DEFAULT'`;
+     * every other adapter leaves it undefined and keeps the FlagNotFound/ERROR
+     * path (`FireweaveWebRuntime.evaluateSync` checks it with strict `===`).
+     */
+    readonly missReason?: 'DEFAULT';
     /** Bring the backend to a usable state. Reject with FireweaveError on failure. */
     initialize(signal?: AbortSignal): Promise<void>;
     /** Fetch every decision for a context. Throws FireweaveError on transport faults. */
@@ -84,4 +99,4 @@ export interface WebBackendAdapter {
     shutdown(): Promise<void>;
     features(): AdapterRuntimeFeatures;
 }
-//# sourceMappingURL=adapter.d.ts.map
+//# sourceMappingURL=ports.d.ts.map