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

package/dist/start/fw.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fw = void 0;
+/**
+ * `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.
+ */
+const index_js_1 = require("../index.js");
+const identity_js_1 = require("./identity.js");
+const names_js_1 = require("./names.js");
+const state_js_1 = require("./state.js");
+function errorDecision(controlPointKey, defaultValue, err) {
+    return {
+        controlPointKey,
+        value: defaultValue,
+        reason: 'ERROR',
+        errorKind: err.kind,
+        errorCode: err.openFeatureErrorCode,
+        errorMessage: err.message,
+        metadata: { 'fireweave.errorKind': err.kind },
+    };
+}
+function notes(controlPointKey, context) {
+    const s = (0, state_js_1.slot)();
+    if (s.config?.mode === 'local' && !Object.prototype.hasOwnProperty.call(s.controlPoints, controlPointKey)) {
+        (0, state_js_1.warnOnce)(s, `[fireweave:local] '${controlPointKey}' is not in your control points (${names_js_1.CONTROL_POINTS_FILE}), so it gets its default. Add it there to try it locally.`);
+    }
+    const perCall = context?.targetingKey;
+    if (typeof perCall === 'string' && perCall !== s.currentKey) {
+        (0, state_js_1.warnOnce)(s, '[fireweave] A per-call targetingKey does not change the decision in the browser: decisions follow fw.identify(). Drop the context argument.');
+    }
+}
+function read(controlPointKey, context, fallback, run) {
+    const s = (0, state_js_1.slot)();
+    if (s.client === undefined) {
+        if (s.state === 'NOT_STARTED') {
+            (0, state_js_1.warnOnce)(s, "[fireweave] A control point was read before start(). Import './fireweave/start' first in your entry module; reads serve their defaults until then.");
+        }
+        return fallback((0, state_js_1.notStartedError)(s.state));
+    }
+    notes(controlPointKey, context);
+    return run(s.client.controlPoints);
+}
+const controlPoints = {
+    evaluate: (controlPointKey, expectedType, defaultValue, context, options) => read(controlPointKey, context, (e) => errorDecision(controlPointKey, defaultValue, e), (c) => c.evaluate(controlPointKey, expectedType, defaultValue, context, options)),
+    getBooleanValue: (controlPointKey, defaultValue, context) => read(controlPointKey, context, () => defaultValue, (c) => c.getBooleanValue(controlPointKey, defaultValue, context)),
+    getStringValue: (controlPointKey, defaultValue, context) => read(controlPointKey, context, () => defaultValue, (c) => c.getStringValue(controlPointKey, defaultValue, context)),
+    getNumberValue: (controlPointKey, defaultValue, context) => read(controlPointKey, context, () => defaultValue, (c) => c.getNumberValue(controlPointKey, defaultValue, context)),
+    getObjectValue: (controlPointKey, defaultValue, context) => read(controlPointKey, context, () => defaultValue, (c) => c.getObjectValue(controlPointKey, defaultValue, context)),
+    getBooleanDetails: (controlPointKey, defaultValue, context) => read(controlPointKey, context, (e) => errorDecision(controlPointKey, defaultValue, e), (c) => c.getBooleanDetails(controlPointKey, defaultValue, context)),
+    getStringDetails: (controlPointKey, defaultValue, context) => read(controlPointKey, context, (e) => errorDecision(controlPointKey, defaultValue, e), (c) => c.getStringDetails(controlPointKey, defaultValue, context)),
+    getNumberDetails: (controlPointKey, defaultValue, context) => read(controlPointKey, context, (e) => errorDecision(controlPointKey, defaultValue, e), (c) => c.getNumberDetails(controlPointKey, defaultValue, context)),
+    getObjectDetails: (controlPointKey, defaultValue, context) => read(controlPointKey, context, (e) => errorDecision(controlPointKey, defaultValue, e), (c) => c.getObjectDetails(controlPointKey, defaultValue, context)),
+};
+/** Run identity changes one at a time, after start settles. */
+function serialized(task) {
+    const s = (0, state_js_1.slot)();
+    const run = s.chain.then(() => s.ready).then(task);
+    s.chain = run.catch(() => undefined);
+    return run;
+}
+/** Re-prefetch under `key` when it differs from the current one. */
+async function switchTo(key) {
+    const s = (0, state_js_1.slot)();
+    if (s.client === undefined || key === s.currentKey)
+        return;
+    s.currentKey = key;
+    try {
+        await s.client.runtime.setContext({ targetingKey: key });
+    }
+    catch {
+        // the runtime reports a failed prefetch through its state; never throw from here
+    }
+}
+exports.fw = Object.freeze({
+    controlPoints: Object.freeze(controlPoints),
+    identify(targetingKey, properties, options = {}) {
+        return serialized(async () => {
+            const s = (0, state_js_1.slot)();
+            if (s.client === undefined) {
+                (0, state_js_1.warnOnce)(s, '[fireweave] fw.identify() ran before FireWeave started; the user was not registered.');
+                return { ok: false, error: (0, state_js_1.notStartedError)(s.state) };
+            }
+            if (typeof targetingKey !== 'string' || targetingKey.trim() === '') {
+                return { ok: false, error: new index_js_1.FireweaveError('InvalidContext') };
+            }
+            const result = await s.client.registerTarget(targetingKey, {
+                kind: options.kind ?? 'user',
+                ...(properties !== undefined ? { properties } : {}),
+            });
+            await switchTo(targetingKey);
+            (0, state_js_1.rememberUser)(s, targetingKey);
+            return result;
+        }).catch(() => ({ ok: false, error: new index_js_1.FireweaveError('Internal') }));
+    },
+    reset() {
+        return serialized(async () => {
+            const s = (0, state_js_1.slot)();
+            (0, state_js_1.rememberUser)(s, undefined);
+            if (s.identity !== undefined)
+                await switchTo(s.identity.deviceId);
+        }).catch(() => undefined);
+    },
+    deviceId: () => (0, state_js_1.slot)().identity?.deviceId,
+    setPersistence(mode) {
+        (0, state_js_1.setPersistenceFor)(mode);
+    },
+    forget() {
+        return serialized(async () => {
+            const s = (0, state_js_1.slot)();
+            (0, state_js_1.setPersistenceFor)('memory');
+            (0, identity_js_1.clearStoredIdentity)();
+            if (s.identity === undefined)
+                return;
+            s.identity = { deviceId: (0, identity_js_1.mintDeviceId)(), durable: false };
+            s.appDeviceId = false;
+            await switchTo(s.identity.deviceId);
+        }).catch(() => undefined);
+    },
+    get ready() {
+        return (0, state_js_1.slot)().ready;
+    },
+    status: () => (0, state_js_1.currentStatus)(),
+    subscribe(listener) {
+        const s = (0, state_js_1.slot)();
+        s.listeners.add(listener);
+        return () => {
+            s.listeners.delete(listener);
+        };
+    },
+    client: () => (0, state_js_1.slot)().client,
+    shutdown: () => (0, state_js_1.shutdownSlot)(),
+});

package/dist/start/identity.d.ts

@@ -0,0 +1,19 @@
+export type Persistence = 'localStorage' | 'memory';
+export interface Identity {
+    /** The anonymous key. */
+    deviceId: string;
+    /** True when the id outlives this page (stored, or supplied by the app). Only durable ids are registered. */
+    durable: boolean;
+    /** The signed-in key restored from storage, if any. */
+    user?: string;
+}
+export declare function readItem(name: string): string | undefined;
+export declare function writeItem(name: string, value: string): boolean;
+export declare function removeItem(name: string): void;
+export declare function mintDeviceId(): string;
+/** Load (or mint) the identity a start boots under. Writes nothing in memory mode. */
+export declare function loadIdentity(persistence: Persistence, deviceIdOption: string | undefined): Identity;
+/** Write the current ids (consent given). Returns whether the device id is now durable. */
+export declare function persistIdentity(identity: Identity, user: string | undefined, appSuppliedDeviceId: boolean): boolean;
+/** Remove everything the start profile stores (consent withdrawn). */
+export declare function clearStoredIdentity(): void;

package/dist/start/identity.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readItem = readItem;
+exports.writeItem = writeItem;
+exports.removeItem = removeItem;
+exports.mintDeviceId = mintDeviceId;
+exports.loadIdentity = loadIdentity;
+exports.persistIdentity = persistIdentity;
+exports.clearStoredIdentity = clearStoredIdentity;
+/**
+ * Browser identity for the start profile: the anonymous device id, the signed-in
+ * key, and how (or whether) they persist.
+ *
+ * The device id key and its dev_ prefix are the scaffolded harness's, so an app
+ * that migrates keeps every returning visitor in the same ramp bucket. Every
+ * storage access is guarded: storage that throws (privacy modes, sandboxed
+ * iframes) means one id per page load, never an error.
+ */
+const names_js_1 = require("./names.js");
+const storage = () => {
+    try {
+        return globalThis.localStorage ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+function readItem(name) {
+    try {
+        const value = storage()?.getItem(name);
+        return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeItem(name, value) {
+    try {
+        const s = storage();
+        if (s === undefined)
+            return false;
+        s.setItem(name, value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function removeItem(name) {
+    try {
+        storage()?.removeItem(name);
+    }
+    catch {
+        // nothing to clean up if storage is unavailable
+    }
+}
+function mintDeviceId() {
+    try {
+        return `dev_${globalThis.crypto.randomUUID()}`;
+    }
+    catch {
+        // randomUUID needs a secure context; the fallback is per page and never stored as stronger than it is.
+        return `dev_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+    }
+}
+/** Load (or mint) the identity a start boots under. Writes nothing in memory mode. */
+function loadIdentity(persistence, deviceIdOption) {
+    const user = persistence === 'localStorage' ? readItem(names_js_1.STORAGE_KEYS.identity) : undefined;
+    const withUser = (identity) => (user !== undefined ? { ...identity, user } : identity);
+    if (deviceIdOption !== undefined)
+        return withUser({ deviceId: deviceIdOption, durable: true });
+    if (persistence === 'memory')
+        return { deviceId: mintDeviceId(), durable: false };
+    const stored = readItem(names_js_1.STORAGE_KEYS.deviceId);
+    if (stored !== undefined)
+        return withUser({ deviceId: stored, durable: true });
+    const deviceId = mintDeviceId();
+    return withUser({ deviceId, durable: writeItem(names_js_1.STORAGE_KEYS.deviceId, deviceId) });
+}
+/** Write the current ids (consent given). Returns whether the device id is now durable. */
+function persistIdentity(identity, user, appSuppliedDeviceId) {
+    if (user !== undefined)
+        writeItem(names_js_1.STORAGE_KEYS.identity, user);
+    if (appSuppliedDeviceId)
+        return true;
+    return writeItem(names_js_1.STORAGE_KEYS.deviceId, identity.deviceId);
+}
+/** Remove everything the start profile stores (consent withdrawn). */
+function clearStoredIdentity() {
+    removeItem(names_js_1.STORAGE_KEYS.deviceId);
+    removeItem(names_js_1.STORAGE_KEYS.identity);
+    removeItem(names_js_1.STORAGE_KEYS.deviceRegistered);
+}

package/dist/start/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fireweaveai/web-sdk/start: one start() call for a browser app.
+ *
+ * ```ts
+ * // src/fireweave/control-points.ts
+ * import { defineControlPoints } from '@fireweaveai/web-sdk/start';
+ * export const controlPoints = defineControlPoints({ 'new-checkout': { local: true } });
+ *
+ * // src/fireweave/start.ts — the first import of your entry module
+ * import { start } from '@fireweaveai/web-sdk/start';
+ * import { controlPoints } from './control-points';
+ * export const ready = start({ controlPoints });
+ *
+ * // anywhere
+ * import { fw } from '@fireweaveai/web-sdk/start';
+ * if (fw.controlPoints.getBooleanValue('new-checkout', false)) { ... }
+ * ```
+ *
+ * The key, endpoint and environment come from the fireweave() Vite plugin
+ * (`@fireweaveai/web-sdk/vite`) or fireweaveDefine() (`/define`) at build
+ * time, or from start() options. This module reads no environment.
+ *
+ * A layer over the unchanged core: it imports only the public barrel
+ * (docs/adr/0012-start-profile.md).
+ */
+export { start, resetForTests } from './state.js';
+export type { StartOptions, StartState, StartProblem, FireweaveWebStatus } from './state.js';
+export { fw } from './fw.js';
+export type { FireweaveWebStart, ControlPoints, IdentifyOptions } from './fw.js';
+export { defineControlPoints } from './control-points.js';
+export type { ControlPointDefinition, ControlPointMap } from './control-points.js';
+export type { Persistence } from './identity.js';
+export type { StartMode, SdkChannel } from './policy.js';
+export { SDK_VERSION, SDK_CHANNEL } from './build-info.js';

package/dist/start/index.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_CHANNEL = exports.SDK_VERSION = exports.defineControlPoints = exports.fw = exports.resetForTests = exports.start = void 0;
+/**
+ * @fireweaveai/web-sdk/start: one start() call for a browser app.
+ *
+ * ```ts
+ * // src/fireweave/control-points.ts
+ * import { defineControlPoints } from '@fireweaveai/web-sdk/start';
+ * export const controlPoints = defineControlPoints({ 'new-checkout': { local: true } });
+ *
+ * // src/fireweave/start.ts — the first import of your entry module
+ * import { start } from '@fireweaveai/web-sdk/start';
+ * import { controlPoints } from './control-points';
+ * export const ready = start({ controlPoints });
+ *
+ * // anywhere
+ * import { fw } from '@fireweaveai/web-sdk/start';
+ * if (fw.controlPoints.getBooleanValue('new-checkout', false)) { ... }
+ * ```
+ *
+ * The key, endpoint and environment come from the fireweave() Vite plugin
+ * (`@fireweaveai/web-sdk/vite`) or fireweaveDefine() (`/define`) at build
+ * time, or from start() options. This module reads no environment.
+ *
+ * A layer over the unchanged core: it imports only the public barrel
+ * (docs/adr/0012-start-profile.md).
+ */
+var state_js_1 = require("./state.js");
+Object.defineProperty(exports, "start", { enumerable: true, get: function () { return state_js_1.start; } });
+Object.defineProperty(exports, "resetForTests", { enumerable: true, get: function () { return state_js_1.resetForTests; } });
+var fw_js_1 = require("./fw.js");
+Object.defineProperty(exports, "fw", { enumerable: true, get: function () { return fw_js_1.fw; } });
+var control_points_js_1 = require("./control-points.js");
+Object.defineProperty(exports, "defineControlPoints", { enumerable: true, get: function () { return control_points_js_1.defineControlPoints; } });
+var build_info_js_1 = require("./build-info.js");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return build_info_js_1.SDK_VERSION; } });
+Object.defineProperty(exports, "SDK_CHANNEL", { enumerable: true, get: function () { return build_info_js_1.SDK_CHANNEL; } });

package/dist/start/names.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Every name the web start profile and its build helpers use, in one place, so
+ * the README, the initialise skill and the error messages cannot drift apart.
+ *
+ * Imported by browser code and by the Node build helpers (node/), so it holds
+ * constants only.
+ */
+/** Build-time variables the Vite plugin and the define helper read. The browser reads none. */
+export declare const BUILD_ENV: Readonly<{
+    key: "FIREWEAVE_BROWSER_KEY";
+    url: "FIREWEAVE_URL";
+    environment: "FIREWEAVE_ENV";
+}>;
+/** Fallback environment name after FIREWEAVE_ENV, at build time. */
+export declare const ENVIRONMENT_FALLBACK = "APP_ENV";
+/** Server secrets the Vite plugin looks for in output chunks. Never injected, never printed. */
+export declare const SERVER_KEY_NAMES: readonly string[];
+/** Environment names that mean "local development" when no key is set. Case-insensitive. */
+export declare const DEV_ENVIRONMENTS: ReadonlySet<string>;
+/** fw-server host for each release channel of this package. */
+export declare const CHANNEL_URLS: Readonly<{
+    production: "https://app-server.fireweave.ai";
+    staging: "https://staging-app-server.fireweave.ai";
+}>;
+/** Hosts always allowed beside a custom endpoint, so local stacks keep working. */
+export declare const LOOPBACK_HOSTS: readonly string[];
+/** The only key family a browser may hold. */
+export declare const BROWSER_KEY_PREFIX = "fw_public_";
+/** localStorage keys. The device id key and its dev_ prefix match the scaffolded harness, so returning visitors keep their bucket. */
+export declare const STORAGE_KEYS: Readonly<{
+    deviceId: "fireweave.device-id";
+    identity: "fireweave.identity";
+    deviceRegistered: "fireweave.device-registered";
+}>;
+/** Where the control-points object lives by convention; named in warnings. */
+export declare const CONTROL_POINTS_FILE = "src/fireweave/control-points.ts";
+/** The identifier the build helpers define and the browser reads behind a typeof guard. */
+export declare const INJECTED_CONFIG_NAME = "__FIREWEAVE_WEB_CONFIG__";

package/dist/start/names.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Every name the web start profile and its build helpers use, in one place, so
+ * the README, the initialise skill and the error messages cannot drift apart.
+ *
+ * Imported by browser code and by the Node build helpers (node/), so it holds
+ * constants only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INJECTED_CONFIG_NAME = exports.CONTROL_POINTS_FILE = exports.STORAGE_KEYS = exports.BROWSER_KEY_PREFIX = exports.LOOPBACK_HOSTS = exports.CHANNEL_URLS = exports.DEV_ENVIRONMENTS = exports.SERVER_KEY_NAMES = exports.ENVIRONMENT_FALLBACK = exports.BUILD_ENV = void 0;
+/** Build-time variables the Vite plugin and the define helper read. The browser reads none. */
+exports.BUILD_ENV = Object.freeze({
+    key: 'FIREWEAVE_BROWSER_KEY',
+    url: 'FIREWEAVE_URL',
+    environment: 'FIREWEAVE_ENV',
+});
+/** Fallback environment name after FIREWEAVE_ENV, at build time. */
+exports.ENVIRONMENT_FALLBACK = 'APP_ENV';
+/** Server secrets the Vite plugin looks for in output chunks. Never injected, never printed. */
+exports.SERVER_KEY_NAMES = Object.freeze(['FIREWEAVE_KEY', 'FW_PROJECT_API_KEY']);
+/** Environment names that mean "local development" when no key is set. Case-insensitive. */
+exports.DEV_ENVIRONMENTS = new Set(['development', 'dev', 'local', 'test']);
+/** fw-server host for each release channel of this package. */
+exports.CHANNEL_URLS = Object.freeze({
+    production: 'https://app-server.fireweave.ai',
+    staging: 'https://staging-app-server.fireweave.ai',
+});
+/** Hosts always allowed beside a custom endpoint, so local stacks keep working. */
+exports.LOOPBACK_HOSTS = Object.freeze(['localhost', '127.0.0.1', '::1']);
+/** The only key family a browser may hold. */
+exports.BROWSER_KEY_PREFIX = 'fw_public_';
+/** localStorage keys. The device id key and its dev_ prefix match the scaffolded harness, so returning visitors keep their bucket. */
+exports.STORAGE_KEYS = Object.freeze({
+    deviceId: 'fireweave.device-id',
+    identity: 'fireweave.identity',
+    deviceRegistered: 'fireweave.device-registered',
+});
+/** Where the control-points object lives by convention; named in warnings. */
+exports.CONTROL_POINTS_FILE = 'src/fireweave/control-points.ts';
+/** The identifier the build helpers define and the browser reads behind a typeof guard. */
+exports.INJECTED_CONFIG_NAME = '__FIREWEAVE_WEB_CONFIG__';

package/dist/start/policy.d.ts

@@ -0,0 +1,70 @@
+export type StartMode = 'remote' | 'local';
+export type SdkChannel = 'staging' | 'production';
+/** A value and where it came from ('start({ key })', 'FIREWEAVE_BROWSER_KEY', ...). */
+export interface Sourced {
+    readonly value: string;
+    readonly source: string;
+}
+export type PolicyReason = 'invalid-mode' | 'missing-key' | 'server-key' | 'wrong-key-family' | 'insecure-url';
+export interface PolicyInput {
+    readonly mode?: unknown;
+    readonly key?: Sourced | undefined;
+    readonly url?: Sourced | undefined;
+    readonly environment?: Sourced | undefined;
+    readonly channel: SdkChannel;
+    /** The variable or option a fix should name, e.g. FIREWEAVE_BROWSER_KEY. */
+    readonly keyVariable: string;
+    /** Where an environment name was looked for, for the missing-key message. */
+    readonly environmentChecked: string;
+}
+export interface PolicyConfig {
+    readonly mode: StartMode;
+    /** Why this mode: the mode option, a present key, or the environment name. */
+    readonly modeSource: 'option' | 'key' | 'environment';
+    /** Remote only. A value starting with '/' is a same-origin proxy path. */
+    readonly url?: string;
+    readonly urlSource?: string;
+    /** Remote only, and absent for the channel default (the core's own list covers it). */
+    readonly allowedHosts?: readonly string[];
+    /** Remote only. Never logged. */
+    readonly key?: string;
+    readonly keySource: string;
+    readonly environment?: string;
+    readonly environmentSource?: string;
+}
+export type PolicyResult = {
+    readonly ok: true;
+    readonly config: PolicyConfig;
+    readonly warnings: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: PolicyReason;
+    readonly variable: string;
+    readonly message: string;
+};
+/** A trimmed, non-empty string with its source, or undefined. Non-strings count as unset. */
+export declare function sourced(value: unknown, source: string): Sourced | undefined;
+/** The first candidate that is set. */
+export declare function firstOf(...candidates: ReadonlyArray<Sourced | undefined>): Sourced | undefined;
+/**
+ * Resolve mode, key and endpoint.
+ *
+ * An explicit mode wins. Otherwise a key means remote; no key and a
+ * development environment name means local; anything else fails closed, so a
+ * missing key never turns into silent local evaluation for real visitors.
+ */
+export declare function resolvePolicy(input: PolicyInput): PolicyResult;
+/**
+ * What the build helpers inject as __FIREWEAVE_WEB_CONFIG__: raw values and
+ * their source names, re-resolved in the browser so explicit start() options
+ * still win. Never carries a server key or the control-points object.
+ */
+export interface InjectedConfig {
+    readonly v: 1;
+    readonly key?: string;
+    readonly keySource?: string;
+    readonly url?: string;
+    readonly urlSource?: string;
+    readonly environment?: string;
+    readonly environmentSource?: string;
+}

package/dist/start/policy.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourced = sourced;
+exports.firstOf = firstOf;
+exports.resolvePolicy = resolvePolicy;
+/**
+ * The web start-profile policy: one pure resolver shared by the browser
+ * start() and the Node build helpers (node/vite.ts, node/define.ts), so a
+ * build and the page it produces can never disagree about mode, key or URL.
+ *
+ * Pure on purpose: no DOM, no env, no core import. Callers hand in values
+ * with their source names; the result is a config, or a failure carrying a
+ * fixed reason code and a message that names sources and variables, never a
+ * value.
+ */
+const names_js_1 = require("./names.js");
+/** A trimmed, non-empty string with its source, or undefined. Non-strings count as unset. */
+function sourced(value, source) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : { value: trimmed, source };
+}
+/** The first candidate that is set. */
+function firstOf(...candidates) {
+    return candidates.find((c) => c !== undefined);
+}
+const fail = (reason, variable, message) => ({
+    ok: false,
+    reason,
+    variable,
+    message: `[fireweave] ${message}`,
+});
+/** Key family check. Messages name the source, never the value. */
+function checkKey(key) {
+    const v = key.value;
+    if (v.startsWith(names_js_1.BROWSER_KEY_PREFIX))
+        return undefined;
+    if (v.startsWith('project-api-key_')) {
+        return fail('server-key', key.source, `The key from ${key.source} is a server key (project-api-key_…), which must never ship to a browser. Use a browser key (fw_public_…) from Project settings, API keys. If a bundle built with this key was deployed, revoke the key.`);
+    }
+    if (/^ph[a-z]_/.test(v)) {
+        return fail('wrong-key-family', key.source, `The key from ${key.source} is an analytics vendor key, not a FireWeave browser key (fw_public_…).`);
+    }
+    if (v.startsWith('fw_org_') || v.startsWith('cli_at_')) {
+        return fail('wrong-key-family', key.source, `The key from ${key.source} is an organisation or CLI token, not a FireWeave browser key (fw_public_…).`);
+    }
+    return fail('wrong-key-family', key.source, `The key from ${key.source} is not a FireWeave browser key (fw_public_…).`);
+}
+const isLoopback = (hostname) => hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+function resolveUrl(url, channel) {
+    if (url === undefined)
+        return { url: names_js_1.CHANNEL_URLS[channel], urlSource: `SDK channel (${channel})` };
+    const value = url.value.replace(/\/+$/, '');
+    if (value.startsWith('//')) {
+        return fail('insecure-url', url.source, `The endpoint from ${url.source} is protocol-relative. Use an https URL or a same-origin path such as '/fw'.`);
+    }
+    // A same-origin proxy path: the browser resolves it against location.origin.
+    if (value.startsWith('/'))
+        return { url: value, urlSource: url.source };
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return fail('insecure-url', url.source, `The endpoint from ${url.source} is not a valid URL.`);
+    }
+    const httpsOk = parsed.protocol === 'https:';
+    const loopbackHttp = parsed.protocol === 'http:' && isLoopback(parsed.hostname);
+    if (!httpsOk && !loopbackHttp) {
+        return fail('insecure-url', url.source, `The endpoint from ${url.source} must use https (http is allowed only for localhost).`);
+    }
+    return { url: value, urlSource: url.source, allowedHosts: [parsed.hostname.replace(/^\[|\]$/g, ''), ...names_js_1.LOOPBACK_HOSTS] };
+}
+function remote(input, key, modeSource, warnings) {
+    const keyProblem = checkKey(key);
+    if (keyProblem !== undefined)
+        return keyProblem;
+    const url = resolveUrl(input.url, input.channel);
+    if ('ok' in url)
+        return url;
+    return { ok: true, config: { mode: 'remote', modeSource, ...url, key: key.value, keySource: key.source }, warnings };
+}
+/**
+ * Resolve mode, key and endpoint.
+ *
+ * An explicit mode wins. Otherwise a key means remote; no key and a
+ * development environment name means local; anything else fails closed, so a
+ * missing key never turns into silent local evaluation for real visitors.
+ */
+function resolvePolicy(input) {
+    const warnings = [];
+    const { mode, key, environment } = input;
+    if (mode !== undefined && mode !== 'remote' && mode !== 'local') {
+        return fail('invalid-mode', 'mode', `start({ mode }) must be 'remote' or 'local'.`);
+    }
+    if (mode === 'local') {
+        if (key !== undefined) {
+            warnings.push(`[fireweave] mode 'local' ignores the key from ${key.source}; nothing is sent to fw-server.`);
+        }
+        return { ok: true, config: { mode: 'local', modeSource: 'option', keySource: 'none' }, warnings };
+    }
+    if (mode === 'remote') {
+        if (key === undefined) {
+            return fail('missing-key', input.keyVariable, `mode 'remote' needs a browser key. Set ${input.keyVariable} to a browser key (fw_public_…).`);
+        }
+        return remote(input, key, 'option', warnings);
+    }
+    if (key !== undefined)
+        return remote(input, key, 'key', warnings);
+    if (environment !== undefined && names_js_1.DEV_ENVIRONMENTS.has(environment.value.toLowerCase())) {
+        return {
+            ok: true,
+            config: {
+                mode: 'local',
+                modeSource: 'environment',
+                keySource: 'none',
+                environment: environment.value,
+                environmentSource: environment.source,
+            },
+            warnings,
+        };
+    }
+    const where = environment === undefined
+        ? `no environment name is set (checked ${input.environmentChecked})`
+        : `the environment is '${environment.value}' (from ${environment.source}), which is not a development name`;
+    return fail('missing-key', input.keyVariable, `${input.keyVariable} is not set and ${where}. Set ${input.keyVariable} to a browser key (fw_public_…), or for local work set FIREWEAVE_ENV=development or pass start({ mode: 'local' }).`);
+}