@fireweaveai/server-sdk-cjs 0.0.0-reserve.0 → 0.0.0-stage

package/dist/start/resolve.js

@@ -1,139 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveStart = resolveStart;
-/**
- * Pure start-profile resolver: options + env + build stamp in, one resolved
- * config out. No I/O, no globals, no timers — every rule here is unit-tested
- * through `resolveStart` alone.
- *
- * Precedence for every value: explicit start() option, then FIREWEAVE_* env,
- * then the default. Reads are lazy:
- * a source is read only if every earlier source was unset, so an explicit
- * option never touches the environment (which matters on Deno).
- */
-const index_js_1 = require("../index.js");
-const env_js_1 = require("./env.js");
-const control_points_js_1 = require("./control-points.js");
-const names_js_1 = require("./names.js");
-const configError = (message) => new index_js_1.FireweaveError('Configuration', { message });
-const optionString = (value, name) => {
-    if (value === undefined || value === null)
-        return undefined;
-    if (typeof value !== 'string')
-        throw configError(`[fireweave] start({ ${name} }) must be a string.`);
-    const trimmed = value.trim();
-    return trimmed === '' ? undefined : trimmed;
-};
-/** First non-empty of: the option, then each env name in order. */
-function pick(option, optionName, names, read) {
-    if (option !== undefined)
-        return { value: option, source: `start({ ${optionName} })` };
-    for (const name of names) {
-        const value = read(name);
-        if (value !== undefined)
-            return { value, source: name };
-    }
-    return undefined;
-}
-/**
- * Key family check, before any request. Messages name the source, never the
- * value. The redactor masks analytics-vendor prefixes, so the message says
- * "analytics vendor key" instead of quoting one.
- */
-function checkKeyFamily(key, source) {
-    if (key.startsWith('fw_public_')) {
-        throw configError(`[fireweave] The key from ${source} is a browser key (fw_public_…). Server apps need a project key (project-api-key_…) from Project settings, API keys.`);
-    }
-    if (/^ph[a-z]_/.test(key)) {
-        throw configError(`[fireweave] The key from ${source} is an analytics vendor key, not a FireWeave project key. Use the project key (project-api-key_…).`);
-    }
-    if (key.startsWith('fw_org_') || key.startsWith('cli_at_')) {
-        throw configError(`[fireweave] The key from ${source} is an organisation or CLI token, not a project key. Use the project key (project-api-key_…).`);
-    }
-}
-function resolveUrl(input, read, build) {
-    const picked = pick(optionString(input.url, 'url'), 'url', [names_js_1.ENV.url], read);
-    if (picked === undefined) {
-        // The channel host is in DEFAULT_ALLOWED_HOSTS, so no custom allowlist.
-        return { url: names_js_1.CHANNEL_URLS[build.channel], urlSource: `SDK channel (${build.channel})` };
-    }
-    const url = picked.value.replace(/\/+$/, '');
-    let hostname;
-    try {
-        hostname = new URL(url).hostname;
-    }
-    catch {
-        throw configError(`[fireweave] The endpoint from ${picked.source} is not a valid URL.`);
-    }
-    const allowedHosts = [hostname.replace(/^\[|\]$/g, ''), ...names_js_1.LOOPBACK_HOSTS];
-    try {
-        (0, index_js_1.assertHostAllowed)(url, allowedHosts);
-    }
-    catch {
-        throw configError(`[fireweave] The endpoint from ${picked.source} must use https (http is allowed only for localhost).`);
-    }
-    return { url, urlSource: picked.source, allowedHosts };
-}
-function resolveKey(input, read) {
-    const picked = pick(optionString(input.key, 'key'), 'key', [names_js_1.ENV.key], read);
-    if (picked !== undefined)
-        checkKeyFamily(picked.value, picked.source);
-    return picked;
-}
-function resolveEnvironment(input, read) {
-    return pick(optionString(input.environment, 'environment'), 'environment', [names_js_1.ENV.environment, ...names_js_1.ENVIRONMENT_FALLBACKS], read);
-}
-function noKeyError(env) {
-    const where = env === undefined
-        ? 'no environment name is set (checked the environment option, FIREWEAVE_ENV, APP_ENV and NODE_ENV)'
-        : `the environment is '${env.value}' (from ${env.source}), which is not a development name`;
-    return configError(`[fireweave] ${names_js_1.ENV.key} is not set and ${where}. Set ${names_js_1.ENV.key} to the project's server key, or for local development set FIREWEAVE_ENV=development or call start({ mode: 'local' }).`);
-}
-/**
- * Resolve start() options against the environment.
- * Throws FireweaveError('Configuration') naming the variable at fault.
- */
-function resolveStart(input, read, build) {
-    const warnings = [];
-    const controlPoints = (0, control_points_js_1.normalizeControlPoints)(input.controlPoints);
-    const base = { controlPoints, channel: build.channel, sdkVersion: build.version };
-    if (input.mode !== undefined && input.mode !== 'remote' && input.mode !== 'local') {
-        throw configError(`[fireweave] start({ mode }) must be 'remote' or 'local'.`);
-    }
-    if (input.mode === 'local') {
-        // The key is ignored. Look only to warn, and never fail on a refused read.
-        const ignored = resolveKeyQuietly(input, read);
-        if (ignored !== undefined) {
-            warnings.push(`[fireweave] start({ mode: 'local' }) ignores the key from ${ignored}; nothing is sent to fw-server.`);
-        }
-        return { ...base, mode: 'local', modeSource: 'option', keySource: 'none', warnings };
-    }
-    const key = resolveKey(input, read);
-    if (input.mode === 'remote') {
-        if (key === undefined) {
-            throw configError(`[fireweave] start({ mode: 'remote' }) needs a key. Set ${names_js_1.ENV.key} or pass start({ key }).`);
-        }
-        return { ...base, mode: 'remote', modeSource: 'option', ...resolveUrl(input, read, build), key: key.value, keySource: key.source, warnings };
-    }
-    if (key !== undefined) {
-        return { ...base, mode: 'remote', modeSource: 'key', ...resolveUrl(input, read, build), key: key.value, keySource: key.source, warnings };
-    }
-    const env = resolveEnvironment(input, read);
-    if (env !== undefined && names_js_1.DEV_ENVIRONMENTS.has(env.value.toLowerCase())) {
-        return {
-            ...base,
-            mode: 'local',
-            modeSource: 'environment',
-            keySource: 'none',
-            environment: env.value,
-            environmentSource: env.source,
-            warnings,
-        };
-    }
-    throw noKeyError(env);
-}
-function resolveKeyQuietly(input, read) {
-    if (typeof input.key === 'string' && input.key.trim() !== '')
-        return 'start({ key })';
-    return (0, env_js_1.quiet)(read)(names_js_1.ENV.key) !== undefined ? names_js_1.ENV.key : undefined;
-}

package/dist/start/state.d.ts

@@ -1,96 +0,0 @@
-/**
- * start() and the process-wide singleton behind `fw`.
- *
- * One slot per process (or worker thread) at a Symbol.for key on globalThis,
- * so two bundled copies of this package share one client. start() is
- * synchronous: it resolves and validates everything up front, throws a
- * Configuration error for bad config, then hands off to the unchanged core
- * initFireweave(). Reads await readiness and never throw.
- *
- * A read that happens before any start() schedules an env-only start on the
- * next macrotask. An ES module graph without top-level await evaluates in one
- * job, so an entrypoint that imports ./fireweave/start first always wins.
- */
-import { FireweaveError, type FireweaveClient, type FireweaveErrorKind, type FireweaveRemoteAdapterOptions } from '../index.js';
-import { type EnvReader } from './env.js';
-import { type ControlPointMap } from './control-points.js';
-import { type InstanceKey } from './instance.js';
-import { type ResolvedStart, type SdkChannel, type StartMode } from './resolve.js';
-export interface StartOptions {
-    /** Control points and their local values; import from src/fireweave/control-points.ts. */
-    readonly controlPoints?: ControlPointMap;
-    /** Force a mode. Without it: a key means remote; no key means local only in a dev environment. */
-    readonly mode?: StartMode;
-    /** Environment name used to infer the mode, instead of FIREWEAVE_ENV, APP_ENV or NODE_ENV. */
-    readonly environment?: string;
-    /** fw-server URL. Default: FIREWEAVE_URL, else this SDK build's channel host. */
-    readonly url?: string;
-    /** Project key (project-api-key_…). Default: FIREWEAVE_KEY. */
-    readonly key?: string;
-    /** Stable id for this process in server-subject reads. Default: FIREWEAVE_INSTANCE_ID, else the host. */
-    readonly instanceId?: string;
-    /** Read these values instead of the process environment (tests, Workers bindings). */
-    readonly env?: Readonly<Record<string, unknown>>;
-    /** Where [fireweave] lines go. Default: console. Not part of the idempotency check. */
-    readonly log?: (line: string) => void;
-    /** Transport override for tests. Not part of the idempotency check. */
-    readonly fetch?: FireweaveRemoteAdapterOptions['fetch'];
-}
-export type StartState = 'unstarted' | 'starting' | 'ready' | 'failed' | 'shutdown';
-export interface FireweaveStatus {
-    readonly state: StartState;
-    readonly mode?: StartMode;
-    readonly modeSource?: ResolvedStart['modeSource'];
-    readonly channel: SdkChannel;
-    readonly sdkVersion: string;
-    /** fw-server host name only: never a path or a credential. */
-    readonly host?: string;
-    readonly endpointSource?: string;
-    readonly keySource?: string;
-    readonly environment?: string;
-    readonly controlPointCount?: number;
-    /** Why start failed, when it did. Already redacted. */
-    readonly error?: string;
-    /**
-     * The kind of the latest failed fw-server request (Authentication,
-     * Authorization, RateLimited, Network, Timeout or BackendUnavailable).
-     * Sticky: a later success does not clear it; a fresh start() does.
-     */
-    readonly lastErrorKind?: FireweaveErrorKind;
-}
-interface Deferred<T> {
-    readonly promise: Promise<T>;
-    readonly resolve: (value: T | PromiseLike<T>) => void;
-}
-interface Slot {
-    readonly protocol: 1;
-    state: StartState;
-    signature?: string;
-    implicit: boolean;
-    resolved?: ResolvedStart;
-    ready: Deferred<FireweaveClient | undefined>;
-    client?: FireweaveClient | undefined;
-    error?: FireweaveError;
-    implicitScheduled: boolean;
-    read?: EnvReader;
-    instanceIdOption?: string;
-    instance?: InstanceKey;
-    log: (line: string) => void;
-    readonly warned: Set<string>;
-    lastErrorKind?: FireweaveErrorKind;
-    /** fw-server failure groups already logged; one line each for the life of the process. */
-    readonly diagnosed: Set<string>;
-}
-export declare function slot(): Slot;
-export declare function warnOnce(s: Slot, line: string): void;
-/** Start FireWeave for this process. Synchronous; call once, from src/fireweave/start.ts. */
-export declare function start(options?: StartOptions): void;
-export declare function startWith(options: StartOptions, implicit: boolean): void;
-/** The client once start() settles; undefined when start failed. Schedules an implicit start if none ran. */
-export declare function ensureClient(): Promise<FireweaveClient | undefined>;
-export declare function currentStatus(): FireweaveStatus;
-export declare function instanceKeyFor(): string;
-export declare function shutdownSlot(): Promise<void>;
-/** Test only: shut down and forget the singleton so the next start() begins fresh. */
-export declare function resetForTests(): Promise<void>;
-export {};

package/dist/start/state.js

@@ -1,303 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.slot = slot;
-exports.warnOnce = warnOnce;
-exports.start = start;
-exports.startWith = startWith;
-exports.ensureClient = ensureClient;
-exports.currentStatus = currentStatus;
-exports.instanceKeyFor = instanceKeyFor;
-exports.shutdownSlot = shutdownSlot;
-exports.resetForTests = resetForTests;
-/**
- * start() and the process-wide singleton behind `fw`.
- *
- * One slot per process (or worker thread) at a Symbol.for key on globalThis,
- * so two bundled copies of this package share one client. start() is
- * synchronous: it resolves and validates everything up front, throws a
- * Configuration error for bad config, then hands off to the unchanged core
- * initFireweave(). Reads await readiness and never throw.
- *
- * A read that happens before any start() schedules an env-only start on the
- * next macrotask. An ES module graph without top-level await evaluates in one
- * job, so an entrypoint that imports ./fireweave/start first always wins.
- */
-const index_js_1 = require("../index.js");
-const build_info_js_1 = require("./build-info.js");
-const env_js_1 = require("./env.js");
-const control_points_js_1 = require("./control-points.js");
-const instance_js_1 = require("./instance.js");
-const resolve_js_1 = require("./resolve.js");
-const deferred = () => {
-    let resolve;
-    const promise = new Promise((r) => {
-        resolve = r;
-    });
-    return { promise, resolve };
-};
-const SLOT_KEY = Symbol.for('@fireweaveai/server-sdk/start');
-const defaultLog = (line) => {
-    if (line.startsWith('[fireweave:local]'))
-        console.info(line);
-    else
-        console.warn(line);
-};
-const freshSlot = () => ({
-    protocol: 1,
-    state: 'unstarted',
-    implicit: false,
-    ready: deferred(),
-    implicitScheduled: false,
-    log: defaultLog,
-    warned: new Set(),
-    diagnosed: new Set(),
-});
-function slot() {
-    const g = globalThis;
-    const existing = g[SLOT_KEY];
-    if (existing !== undefined) {
-        if (existing.protocol !== 1) {
-            throw new index_js_1.FireweaveError('Configuration', {
-                message: '[fireweave] Two incompatible copies of @fireweaveai/server-sdk are loaded. Deduplicate the dependency.',
-            });
-        }
-        return existing;
-    }
-    const created = freshSlot();
-    g[SLOT_KEY] = created;
-    return created;
-}
-function warnOnce(s, line) {
-    if (s.warned.has(line))
-        return;
-    s.warned.add(line);
-    s.log(line);
-}
-const signatureOf = (r, instanceId) => (0, index_js_1.stableStringify)({
-    mode: r.mode,
-    url: r.url ?? null,
-    key: r.key ?? null,
-    allowedHosts: r.allowedHosts !== undefined ? [...r.allowedHosts] : null,
-    instanceId: instanceId ?? null,
-    // Seeds only matter in local mode; remote ignores them, so an env-only
-    // implicit start followed by start({ controlPoints }) under a key is not a conflict.
-    ...(r.mode === 'local' ? { controlPoints: (0, control_points_js_1.toLocalControlPoints)(r.controlPoints) } : {}),
-});
-function localLine(r) {
-    const why = r.modeSource === 'option'
-        ? "start({ mode: 'local' })"
-        : `no FIREWEAVE_KEY; environment '${r.environment ?? ''}' from ${r.environmentSource ?? 'env'}`;
-    const n = Object.keys(r.controlPoints).length;
-    return `[fireweave:local] Local mode (${why}). Serving ${n} control point${n === 1 ? '' : 's'} from your control-points object; nothing is sent to fw-server.`;
-}
-/** The kind the core's remote adapter reports for an HTTP status, or undefined for a success. */
-function kindForStatus(status) {
-    if (status < 400)
-        return undefined;
-    if (status === 401)
-        return 'Authentication';
-    if (status === 403)
-        return 'Authorization';
-    if (status === 429)
-        return 'RateLimited';
-    return 'BackendUnavailable';
-}
-/**
- * SP-27: a refused key, a rate limit or an unreachable fw-server is logged
- * once per group for the life of the process and kept as lastErrorKind, so a
- * revoked key does not look like a rollout at 0%. Lines name the key's source
- * and the host, never the key.
- */
-function observeFailure(s, token, r, kind, detail) {
-    if (s.ready !== token)
-        return; // a response for a client that was shut down or replaced
-    s.lastErrorKind = kind;
-    const host = r.url !== undefined ? new URL(r.url).host : 'fw-server';
-    let group;
-    let line;
-    switch (kind) {
-        case 'Authentication':
-            group = 'key-rejected-401';
-            line = `[fireweave] fw-server at ${host} rejected the key from ${r.keySource} (HTTP 401): it is wrong, revoked or from another project. Reads serve their defaults; this is not a rollout at 0%.`;
-            break;
-        case 'Authorization':
-            group = 'key-rejected-403';
-            line = `[fireweave] fw-server at ${host} refused the key from ${r.keySource} for this project or environment (HTTP 403). Reads serve their defaults; this is not a rollout at 0%.`;
-            break;
-        case 'RateLimited':
-            group = 'rate-limited';
-            line = `[fireweave] fw-server at ${host} rate-limited the key from ${r.keySource} (HTTP 429). Reads serve their defaults until a request succeeds.`;
-            break;
-        default:
-            group = 'unreachable';
-            line = `[fireweave] Could not reach fw-server at ${host} (endpoint from ${r.urlSource ?? 'the SDK channel'}; ${detail}): offline, a firewall, or the wrong endpoint. Reads serve their defaults until a request succeeds.`;
-    }
-    if (s.diagnosed.has(group))
-        return;
-    s.diagnosed.add(group);
-    try {
-        s.log(line);
-    }
-    catch {
-        // A faulty log sink must not turn into a transport failure.
-    }
-}
-/** The transport handed to the core, observed. The core's behaviour is unchanged. */
-function observedTransport(s, token, r, base) {
-    return async (url, init) => {
-        const call = base ?? globalThis.fetch;
-        let response;
-        try {
-            response = await call(url, init);
-        }
-        catch (err) {
-            // The same split the core makes: its own deadline aborts the request.
-            const timedOut = err instanceof Error && err.name === 'AbortError';
-            observeFailure(s, token, r, timedOut ? 'Timeout' : 'Network', timedOut ? 'timed out' : 'network error');
-            throw err;
-        }
-        const kind = kindForStatus(response.status);
-        if (kind !== undefined)
-            observeFailure(s, token, r, kind, `HTTP ${response.status}`);
-        return response;
-    };
-}
-function initOptions(r, options, s, token) {
-    if (r.mode === 'local') {
-        return { mode: 'local', local: { controlPoints: (0, control_points_js_1.toLocalControlPoints)(r.controlPoints), log: (line) => s.log(line) } };
-    }
-    return {
-        mode: 'remote',
-        apiKey: r.key,
-        apiUrl: r.url,
-        ...(r.allowedHosts !== undefined ? { allowedHosts: r.allowedHosts } : {}),
-        fetch: observedTransport(s, token, r, options.fetch),
-    };
-}
-/** Start FireWeave for this process. Synchronous; call once, from src/fireweave/start.ts. */
-function start(options = {}) {
-    startWith(options, false);
-}
-function startWith(options, implicit) {
-    const s = slot();
-    if (s.state === 'shutdown' || s.state === 'failed') {
-        // Warnings and fw-server failure lines are once per process, across restarts.
-        Object.assign(s, freshSlot(), { warned: s.warned, diagnosed: s.diagnosed });
-        delete s.lastErrorKind; // freshSlot() has no such key, so assign alone would keep it
-    }
-    const read = options.env !== undefined ? (0, env_js_1.envFromBag)(options.env) : (0, env_js_1.processEnv)();
-    const resolved = (0, resolve_js_1.resolveStart)(options, read, { version: build_info_js_1.SDK_VERSION, channel: build_info_js_1.SDK_CHANNEL });
-    const signature = signatureOf(resolved, options.instanceId);
-    if (s.state === 'starting' || s.state === 'ready') {
-        if (signature === s.signature)
-            return;
-        throw new index_js_1.FireweaveError('Configuration', {
-            message: s.implicit
-                ? "[fireweave] A control point was read before start() ran, so FireWeave started from the environment alone. Import './fireweave/start' as the first import of your entrypoint."
-                : '[fireweave] start() was already called with a different configuration. Call start() once, from src/fireweave/start.ts.',
-        });
-    }
-    if (options.instanceId !== undefined && s.instance !== undefined && s.instance.value !== options.instanceId) {
-        throw new index_js_1.FireweaveError('Configuration', {
-            message: '[fireweave] start({ instanceId }) differs from the instanceKey() already handed out. Pass instanceId on the first start().',
-        });
-    }
-    // Only a start that actually begins sets the log sink: an identical second
-    // start() is a no-op and a conflicting one throws, and neither may swap it.
-    if (!implicit && options.log !== undefined)
-        s.log = options.log;
-    s.state = 'starting';
-    s.signature = signature;
-    s.implicit = implicit;
-    s.resolved = resolved;
-    s.read = read;
-    if (options.instanceId !== undefined)
-        s.instanceIdOption = options.instanceId;
-    for (const w of resolved.warnings)
-        warnOnce(s, w);
-    if (resolved.mode === 'local')
-        s.log(localLine(resolved));
-    const ready = s.ready;
-    const pending = (0, index_js_1.initFireweave)(initOptions(resolved, options, s, ready)).then((client) => {
-        if (s.ready !== ready)
-            return undefined; // superseded by shutdown/restart
-        s.state = 'ready';
-        s.client = client;
-        return client;
-    }, (err) => {
-        if (s.ready !== ready)
-            return undefined;
-        s.state = 'failed';
-        s.error = (0, index_js_1.isFireweaveError)(err) ? err : new index_js_1.FireweaveError('Internal', { cause: err });
-        warnOnce(s, `[fireweave] start failed: ${s.error.message}. Reads serve their defaults.`);
-        return undefined;
-    });
-    ready.resolve(pending);
-}
-/** The client once start() settles; undefined when start failed. Schedules an implicit start if none ran. */
-function ensureClient() {
-    const s = slot();
-    if (s.state === 'unstarted' && !s.implicitScheduled) {
-        s.implicitScheduled = true;
-        setTimeout(() => {
-            if (s.state !== 'unstarted')
-                return;
-            try {
-                startWith({}, true);
-            }
-            catch (err) {
-                s.state = 'failed';
-                s.error = (0, index_js_1.isFireweaveError)(err) ? err : new index_js_1.FireweaveError('Internal', { cause: err });
-                warnOnce(s, `${s.error.message} (FireWeave was not started; reads serve their defaults.)`);
-                s.ready.resolve(undefined);
-            }
-        }, 0);
-    }
-    return s.ready.promise;
-}
-function currentStatus() {
-    const s = slot();
-    const r = s.resolved;
-    return {
-        state: s.state,
-        channel: r?.channel ?? build_info_js_1.SDK_CHANNEL,
-        sdkVersion: r?.sdkVersion ?? build_info_js_1.SDK_VERSION,
-        ...(r !== undefined
-            ? {
-                mode: r.mode,
-                modeSource: r.modeSource,
-                keySource: r.keySource,
-                controlPointCount: Object.keys(r.controlPoints).length,
-                ...(r.url !== undefined ? { host: new URL(r.url).hostname, endpointSource: r.urlSource } : {}),
-                ...(r.environment !== undefined ? { environment: r.environment } : {}),
-            }
-            : {}),
-        ...(s.error !== undefined ? { error: s.error.message } : {}),
-        ...(s.lastErrorKind !== undefined ? { lastErrorKind: s.lastErrorKind } : {}),
-    };
-}
-function instanceKeyFor() {
-    const s = slot();
-    if (s.instance === undefined)
-        s.instance = (0, instance_js_1.deriveInstanceKey)(s.instanceIdOption, s.read ?? (0, env_js_1.processEnv)());
-    return s.instance.value;
-}
-async function shutdownSlot() {
-    const s = slot();
-    const client = s.state === 'starting' ? await s.ready.promise : s.client;
-    s.state = 'shutdown';
-    s.client = undefined;
-    s.ready = deferred();
-    s.ready.resolve(undefined);
-    s.implicitScheduled = true; // no implicit restart after an explicit shutdown
-    if (client !== undefined)
-        await client.shutdown();
-}
-/** Test only: shut down and forget the singleton so the next start() begins fresh. */
-async function resetForTests() {
-    const g = globalThis;
-    const s = g[SLOT_KEY];
-    if (s?.client !== undefined)
-        await s.client.shutdown().catch(() => undefined);
-    delete g[SLOT_KEY];
-}