@fireweaveai/web-sdk 2.3.0-staging.2 → 3.0.0-staging.1

package/dist/build/node/define.js

@@ -0,0 +1,35 @@
+/**
+ * @fireweaveai/web-sdk/define — the start profile's build check for bundlers
+ * other than Vite (Next.js, webpack, esbuild, Rollup). No vite import.
+ *
+ *   // next.config.mjs (or any build config)
+ *   import { fireweaveDefine } from '@fireweaveai/web-sdk/define';
+ *   const define = fireweaveDefine(); // throws if the build would ship without a usable key
+ *   // webpack: new webpack.DefinePlugin(define) · esbuild: { define } · Rollup: replace({ values: define })
+ *
+ * Reads process.env only: FIREWEAVE_BROWSER_KEY (or `keyVariable`),
+ * FIREWEAVE_URL, and the environment name FIREWEAVE_ENV, then APP_ENV, then
+ * NODE_ENV. Same policy and messages as the Vite plugin.
+ */
+import { BUILD_ENV, ENVIRONMENT_FALLBACK, INJECTED_CONFIG_NAME } from '../src/start/names.js';
+import { sourced } from '../src/start/policy.js';
+import { resolveBuild, summaryLine } from './shared.js';
+function resolveFromEnv(options) {
+    const env = options.env ?? process.env;
+    const lookup = (name) => sourced(env[name], name);
+    const resolved = resolveBuild(options, lookup, options.keyVariable ?? BUILD_ENV.key, [BUILD_ENV.environment, ENVIRONMENT_FALLBACK, 'NODE_ENV']);
+    const log = options.log ?? ((line) => console.info(line));
+    for (const w of resolved.warnings)
+        log(w);
+    log(summaryLine(resolved.config));
+    return resolved;
+}
+/** Fail the build (throw) when the start profile would not start; returns the resolved config. */
+export function assertFireweaveBuild(options = {}) {
+    return resolveFromEnv(options).config;
+}
+/** assertFireweaveBuild, plus the define map that hands the result to start(). */
+export function fireweaveDefine(options = {}) {
+    return { [INJECTED_CONFIG_NAME]: JSON.stringify(resolveFromEnv(options).injected) };
+}
+//# sourceMappingURL=define.js.map

package/dist/build/node/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../node/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE9F,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAW3E,SAAS,cAAc,CAAC,OAA+B;IACrD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,IAAI,SAAS,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,oBAAoB,EAAE,UAAU,CAAC,CAAC,CAAC;IAChJ,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAClE,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,QAAQ;QAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAC1C,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,oBAAoB,CAAC,UAAkC,EAAE;IACvE,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;AACxC,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,OAAO,EAAE,CAAC,oBAAoB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;AACtF,CAAC"}

package/dist/build/node/shared.d.ts

@@ -0,0 +1,19 @@
+import { type InjectedConfig, type PolicyConfig, type Sourced } from '../src/start/policy.js';
+/** A variable read at build time: its value and a source label for logs (never the value). */
+export type EnvLookup = (name: string) => Sourced | undefined;
+export interface BuildOptions {
+    /** Browser key. Prefer FIREWEAVE_BROWSER_KEY in the build environment. */
+    readonly key?: string;
+    /** fw-server URL or a same-origin proxy path ('/fw'). Default: FIREWEAVE_URL, else the SDK channel host. */
+    readonly url?: string;
+    /** Environment name for the mode rule. Default: FIREWEAVE_ENV, else APP_ENV. */
+    readonly environment?: string;
+}
+export interface BuildResolution {
+    readonly config: PolicyConfig;
+    readonly injected: InjectedConfig;
+    readonly warnings: readonly string[];
+}
+export declare function resolveBuild(options: BuildOptions, lookup: EnvLookup, keyVariable: string, environmentNames: readonly string[], extraEnvironment?: Sourced): BuildResolution;
+/** One summary line for build output. Names sources, never values. */
+export declare function summaryLine(config: PolicyConfig): string;

package/dist/build/node/shared.js

@@ -0,0 +1,44 @@
+/**
+ * Build-time resolution shared by the Vite plugin and the define helper.
+ * Runs in Node at config time, never in a browser. It reuses the browser's
+ * own policy (src/start/policy.ts), so a build fails for exactly the reasons
+ * the page would.
+ */
+import { SDK_CHANNEL } from '../src/start/build-info.js';
+import { BUILD_ENV, RETIRED_KEY_NAMES } from '../src/start/names.js';
+import { firstOf, resolvePolicy, sourced } from '../src/start/policy.js';
+export function resolveBuild(options, lookup, keyVariable, environmentNames, extraEnvironment) {
+    const key = firstOf(sourced(options.key, 'fireweave({ key })'), lookup(keyVariable));
+    const url = firstOf(sourced(options.url, 'fireweave({ url })'), lookup(BUILD_ENV.url));
+    const environment = firstOf(sourced(options.environment, 'fireweave({ environment })'), ...environmentNames.map((name) => lookup(name)), extraEnvironment);
+    const warnings = [];
+    if (key === undefined) {
+        for (const name of RETIRED_KEY_NAMES) {
+            if (lookup(name) !== undefined) {
+                warnings.push(`[fireweave] ${name} is not read by the start profile: it held a server-family key. Create a browser key (fw_public_…) and set ${keyVariable}.`);
+            }
+        }
+    }
+    const checked = [`fireweave({ environment })`, ...environmentNames, ...(extraEnvironment !== undefined ? [extraEnvironment.source] : [])].join(', ');
+    const policy = resolvePolicy({ key, url, environment, channel: SDK_CHANNEL, keyVariable, environmentChecked: checked });
+    if (!policy.ok)
+        throw new Error(policy.message);
+    const config = policy.config;
+    const injected = {
+        v: 1,
+        ...(config.mode === 'remote' && key !== undefined ? { key: key.value, keySource: key.source } : {}),
+        ...(url !== undefined ? { url: url.value, urlSource: url.source } : {}),
+        ...(environment !== undefined ? { environment: environment.value, environmentSource: environment.source } : {}),
+    };
+    return { config, injected, warnings: [...warnings, ...policy.warnings] };
+}
+/** One summary line for build output. Names sources, never values. */
+export function summaryLine(config) {
+    if (config.mode === 'local') {
+        const why = config.modeSource === 'environment' ? `environment '${config.environment ?? ''}' from ${config.environmentSource ?? ''}` : 'mode option';
+        return `[fireweave] local mode (${why}): values come from your control-points object; nothing is sent to fw-server.`;
+    }
+    const host = config.url !== undefined && !config.url.startsWith('/') ? new URL(config.url).host : config.url;
+    return `[fireweave] remote mode: browser key from ${config.keySource}, fw-server ${host} (${config.urlSource ?? ''}).`;
+}
+//# sourceMappingURL=shared.js.map

package/dist/build/node/shared.js.map

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

package/dist/build/node/vite.d.ts

@@ -0,0 +1,53 @@
+import { type BuildOptions } from './shared.js';
+export type FireweavePluginOptions = BuildOptions;
+/** The subset of Vite's types the plugin touches, so the package needs no vite types to build. */
+interface UserConfigLike {
+    readonly root?: string;
+    readonly envDir?: string | false;
+    readonly build?: {
+        readonly lib?: unknown;
+    };
+}
+interface ConfigEnvLike {
+    readonly command: 'serve' | 'build';
+    readonly mode: string;
+    readonly isPreview?: boolean;
+}
+interface ResolvedConfigLike {
+    readonly envPrefix?: string | readonly string[];
+    readonly build?: {
+        readonly ssr?: unknown;
+    };
+}
+type OutputFileLike = {
+    readonly type: 'chunk';
+    readonly code: string;
+} | {
+    readonly type: 'asset';
+    readonly source: string | Uint8Array;
+};
+interface PluginContextLike {
+    readonly environment?: {
+        readonly config?: {
+            readonly consumer?: string;
+        };
+    };
+}
+export type LoadEnv = (mode: string, envDir: string, prefixes: string[]) => Record<string, string> | Promise<Record<string, string>>;
+export interface FireweaveVitePlugin {
+    readonly name: 'fireweave';
+    readonly enforce: 'pre';
+    config(userConfig: UserConfigLike, env: ConfigEnvLike): Promise<Record<string, unknown> | undefined>;
+    configResolved(config: ResolvedConfigLike): void;
+    generateBundle(this: PluginContextLike, options: unknown, bundle: Readonly<Record<string, OutputFileLike>>): void;
+}
+/** Test seam: the env-file loader and the process environment. */
+export interface PluginDeps {
+    readonly loadEnv?: LoadEnv;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly log?: (line: string) => void;
+}
+export declare function createFireweavePlugin(options?: FireweavePluginOptions, deps?: PluginDeps): FireweaveVitePlugin;
+/** The fireweave() Vite plugin. Add it to `plugins` in vite.config.ts (or a framework's `vite.plugins`). */
+export declare function fireweave(options?: FireweavePluginOptions): FireweaveVitePlugin;
+export {};

package/dist/build/node/vite.js

@@ -0,0 +1,103 @@
+/**
+ * @fireweaveai/web-sdk/vite — the fireweave() Vite plugin.
+ *
+ *   // vite.config.ts
+ *   import { fireweave } from '@fireweaveai/web-sdk/vite';
+ *   export default defineConfig({ plugins: [fireweave()] });
+ *
+ * At config time (Node) it reads FIREWEAVE_BROWSER_KEY, FIREWEAVE_URL and the
+ * environment name from the process environment and Vite's env files, applies
+ * the start profile's policy, and either fails the dev server or build with a
+ * message naming the variable, or injects the result as
+ * __FIREWEAVE_WEB_CONFIG__ for start() to pick up. After a client build it
+ * fails if a server key reached any output file.
+ *
+ * Environment name: FIREWEAVE_ENV, then APP_ENV; the dev server and Vitest
+ * also fall back to Vite's mode. A build never infers local mode from
+ * `--mode development`, so a production build without a key fails.
+ *
+ * Node build tooling: nothing here ships to the browser. vite is an optional
+ * peer and is loaded lazily, so this file has no static import of it.
+ */
+import { resolve as resolvePath } from 'node:path';
+import { BUILD_ENV, ENVIRONMENT_FALLBACK, INJECTED_CONFIG_NAME, SERVER_KEY_NAMES } from '../src/start/names.js';
+import { sourced } from '../src/start/policy.js';
+import { resolveBuild, summaryLine } from './shared.js';
+const ENV_PREFIXES = ['FIREWEAVE_', ENVIRONMENT_FALLBACK, 'VITE_FW_', 'PUBLIC_FW_'];
+const SERVER_KEY_PATTERN = /project-api-key_[A-Za-z0-9_-]{8,}/;
+async function viteLoadEnv() {
+    const specifier = 'vite';
+    const vite = (await import(specifier));
+    return vite.loadEnv;
+}
+/** Mirror Vite's env-file location: envDir resolved against the resolved root; false disables files. */
+function envDirOf(userConfig) {
+    if (userConfig.envDir === false)
+        return false;
+    const root = resolvePath(userConfig.root ?? process.cwd());
+    return userConfig.envDir !== undefined ? resolvePath(root, userConfig.envDir) : root;
+}
+export function createFireweavePlugin(options = {}, deps = {}) {
+    const env = deps.env ?? process.env;
+    const log = deps.log ?? ((line) => console.info(line));
+    let skip = false;
+    let clientSsr = false;
+    return {
+        name: 'fireweave',
+        enforce: 'pre',
+        async config(userConfig, configEnv) {
+            if (configEnv.isPreview === true) {
+                skip = true;
+                return undefined;
+            }
+            if (userConfig.build?.lib !== undefined && userConfig.build.lib !== false) {
+                skip = true;
+                log('[fireweave] build.lib: no config injected. A library must not bake in an app key; the app that bundles it runs fireweave().');
+                return undefined;
+            }
+            const envDir = envDirOf(userConfig);
+            const loadEnv = deps.loadEnv ?? (envDir === false ? undefined : await viteLoadEnv());
+            const files = envDir === false || loadEnv === undefined ? {} : await loadEnv(configEnv.mode, envDir, ENV_PREFIXES);
+            const lookup = (name) => sourced(env[name], name) ?? sourced(files[name], `${name} (.env files)`);
+            const viteMode = configEnv.command === 'serve' ? sourced(configEnv.mode, `Vite mode '${configEnv.mode}'`) : undefined;
+            const resolved = resolveBuild(options, lookup, BUILD_ENV.key, [BUILD_ENV.environment, ENVIRONMENT_FALLBACK], viteMode);
+            for (const w of resolved.warnings)
+                log(w);
+            log(summaryLine(resolved.config));
+            return {
+                define: { [INJECTED_CONFIG_NAME]: JSON.stringify(resolved.injected) },
+                // Keep the SDK out of the dep pre-bundle so the injected config is never cached stale.
+                optimizeDeps: { exclude: ['@fireweaveai/web-sdk'] },
+            };
+        },
+        configResolved(config) {
+            if (skip)
+                return;
+            const prefixes = config.envPrefix === undefined ? ['VITE_'] : typeof config.envPrefix === 'string' ? [config.envPrefix] : [...config.envPrefix];
+            const exposed = SERVER_KEY_NAMES.filter((name) => prefixes.some((p) => p !== '' && name.startsWith(p)));
+            if (exposed.length > 0) {
+                throw new Error(`[fireweave] envPrefix would expose ${exposed.join(' and ')} to the browser bundle. Remove that prefix; the browser key is injected by fireweave() as ${BUILD_ENV.key}.`);
+            }
+            clientSsr = config.build?.ssr !== undefined && config.build.ssr !== false;
+        },
+        generateBundle(_options, bundle) {
+            if (skip)
+                return;
+            const serverEnvironment = this.environment?.config?.consumer === 'server' || (this.environment === undefined && clientSsr);
+            if (serverEnvironment)
+                return;
+            const secrets = SERVER_KEY_NAMES.map((name) => env[name]?.trim()).filter((v) => v !== undefined && v.length >= 8);
+            for (const [fileName, file] of Object.entries(bundle)) {
+                const text = file.type === 'chunk' ? file.code : typeof file.source === 'string' ? file.source : '';
+                if (SERVER_KEY_PATTERN.test(text) || secrets.some((secret) => text.includes(secret))) {
+                    throw new Error(`[fireweave] ${fileName} contains a server key. Server keys must never ship to a browser: remove it from client code, and revoke it if this build was deployed.`);
+                }
+            }
+        },
+    };
+}
+/** The fireweave() Vite plugin. Add it to `plugins` in vite.config.ts (or a framework's `vite.plugins`). */
+export function fireweave(options = {}) {
+    return createFireweavePlugin(options);
+}
+//# sourceMappingURL=vite.js.map

package/dist/build/node/vite.js.map

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

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

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

package/dist/build/src/start/build-info.js

@@ -0,0 +1,7 @@
+// 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.
+export const SDK_VERSION = '3.0.0-staging.1';
+export const SDK_CHANNEL = 'staging';
+//# sourceMappingURL=build-info.js.map

package/dist/build/src/start/build-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-info.js","sourceRoot":"","sources":["../../../../src/start/build-info.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,2EAA2E;AAC3E,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,MAAM,CAAC,MAAM,WAAW,GAA6B,SAAS,CAAC"}

package/dist/build/src/start/names.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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";
+/**
+ * Names the scaffolded harness used for the browser key. They held a project
+ * (server-family) key, which the start profile refuses, so they are detected
+ * only to explain what to set instead.
+ */
+export declare const RETIRED_KEY_NAMES: readonly string[];
+/** 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/build/src/start/names.js

@@ -0,0 +1,45 @@
+/**
+ * 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 const BUILD_ENV = Object.freeze({
+    key: 'FIREWEAVE_BROWSER_KEY',
+    url: 'FIREWEAVE_URL',
+    environment: 'FIREWEAVE_ENV',
+});
+/** Fallback environment name after FIREWEAVE_ENV, at build time. */
+export const ENVIRONMENT_FALLBACK = 'APP_ENV';
+/**
+ * Names the scaffolded harness used for the browser key. They held a project
+ * (server-family) key, which the start profile refuses, so they are detected
+ * only to explain what to set instead.
+ */
+export const RETIRED_KEY_NAMES = Object.freeze(['VITE_FW_PROJECT_API_KEY', 'PUBLIC_FW_PROJECT_API_KEY']);
+/** Server secrets the Vite plugin looks for in output chunks. Never injected, never printed. */
+export const SERVER_KEY_NAMES = Object.freeze(['FIREWEAVE_KEY', 'FW_PROJECT_API_KEY']);
+/** Environment names that mean "local development" when no key is set. Case-insensitive. */
+export const DEV_ENVIRONMENTS = new Set(['development', 'dev', 'local', 'test']);
+/** fw-server host for each release channel of this package. */
+export const 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. */
+export const LOOPBACK_HOSTS = Object.freeze(['localhost', '127.0.0.1', '::1']);
+/** The only key family a browser may hold. */
+export 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 const 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. */
+export const CONTROL_POINTS_FILE = 'src/fireweave/control-points.ts';
+/** The identifier the build helpers define and the browser reads behind a typeof guard. */
+export const INJECTED_CONFIG_NAME = '__FIREWEAVE_WEB_CONFIG__';
+//# sourceMappingURL=names.js.map

package/dist/build/src/start/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../../../src/start/names.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,+FAA+F;AAC/F,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;IACrC,GAAG,EAAE,uBAAuB;IAC5B,GAAG,EAAE,eAAe;IACpB,WAAW,EAAE,eAAe;CAC7B,CAAC,CAAC;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAsB,MAAM,CAAC,MAAM,CAAC,CAAC,yBAAyB,EAAE,2BAA2B,CAAC,CAAC,CAAC;AAE5H,gGAAgG;AAChG,MAAM,CAAC,MAAM,gBAAgB,GAAsB,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,EAAE,oBAAoB,CAAC,CAAC,CAAC;AAE1G,4FAA4F;AAC5F,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAEtG,+DAA+D;AAC/D,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;IACxC,UAAU,EAAE,iCAAiC;IAC7C,OAAO,EAAE,yCAAyC;CACnD,CAAC,CAAC;AAEH,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAsB,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;AAElG,8CAA8C;AAC9C,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE/C,sIAAsI;AACtI,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;IACxC,QAAQ,EAAE,qBAAqB;IAC/B,QAAQ,EAAE,oBAAoB;IAC9B,gBAAgB,EAAE,6BAA6B;CAChD,CAAC,CAAC;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,iCAAiC,CAAC;AAErE,2FAA2F;AAC3F,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC"}

package/dist/build/src/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/build/src/start/policy.js

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+import { BROWSER_KEY_PREFIX, CHANNEL_URLS, DEV_ENVIRONMENTS, LOOPBACK_HOSTS } from './names.js';
+/** A trimmed, non-empty string with its source, or undefined. Non-strings count as unset. */
+export 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. */
+export 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(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: 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, ''), ...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.
+ */
+export 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 && 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' }).`);
+}
+//# sourceMappingURL=policy.js.map

package/dist/build/src/start/policy.js.map

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

package/dist/domain/errors.d.ts

@@ -11,7 +11,7 @@
  * on a machine we do not control, so nothing host-, key-, or response-derived
  * is ever interpolated into one.
  */
-export type FireweaveErrorKind = 'Configuration' | 'Authentication' | 'Authorization' | 'Network' | 'Timeout' | 'RateLimited' | 'BackendUnavailable' | 'MalformedResponse' | 'InvalidContext' | 'FlagNotFound' | 'TypeMismatch' | 'NotReady' | 'AlreadyClosed' | 'UnsupportedCapability' | 'Internal';
+export type FireweaveErrorKind = 'Configuration' | 'Authentication' | 'Authorization' | 'Network' | 'Timeout' | 'RateLimited' | 'BackendUnavailable' | 'MalformedResponse' | 'InvalidContext' | 'ControlPointNotFound' | 'TypeMismatch' | 'NotReady' | 'AlreadyClosed' | 'UnsupportedCapability' | 'Internal';
 export type OpenFeatureErrorCode = 'PROVIDER_NOT_READY' | 'PROVIDER_FATAL' | 'FLAG_NOT_FOUND' | 'PARSE_ERROR' | 'TYPE_MISMATCH' | 'TARGETING_KEY_MISSING' | 'INVALID_CONTEXT' | 'GENERAL';
 export interface ErrorKindSpec {
     readonly message: string;

package/dist/domain/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/domain/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,SAAS,GACT,SAAS,GACT,aAAa,GACb,oBAAoB,GACpB,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,UAAU,GACV,eAAe,GACf,uBAAuB,GACvB,UAAU,CAAC;AAEf,MAAM,MAAM,oBAAoB,GAC5B,oBAAoB,GACpB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,eAAe,GACf,uBAAuB,GACvB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IACpD,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,CA4D7E,CAAC;AAEH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;gBAEjD,IAAI,EAAE,kBAAkB,EAAE,OAAO,GAAE,qBAA0B;CAS1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/domain/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,SAAS,GACT,SAAS,GACT,aAAa,GACb,oBAAoB,GACpB,mBAAmB,GACnB,gBAAgB,GAChB,sBAAsB,GACtB,cAAc,GACd,UAAU,GACV,eAAe,GACf,uBAAuB,GACvB,UAAU,CAAC;AAEf,MAAM,MAAM,oBAAoB,GAC5B,oBAAoB,GACpB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,eAAe,GACf,uBAAuB,GACvB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IACpD,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,CA4D7E,CAAC;AAEH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;gBAEjD,IAAI,EAAE,kBAAkB,EAAE,OAAO,GAAE,qBAA0B;CAS1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE"}

package/dist/domain/errors.js

@@ -45,7 +45,7 @@ export const ERROR_TAXONOMY = Object.freeze({
         openFeatureErrorCode: 'INVALID_CONTEXT',
         retryable: false,
     },
-    FlagNotFound: {
+    ControlPointNotFound: {
         message: 'flag not found',
         openFeatureErrorCode: 'FLAG_NOT_FOUND',
         retryable: false,