@fireweaveai/web-sdk 2.1.0

package/dist/adapters/remote.js

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

package/dist/adapters/remote.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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).
+ *
+ * One divergence, 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 './errors.js';
+import type { ContextInput } from './context.js';
+import type { FireweaveWebRuntime, ExpectedFlagType } from './runtime.js';
+import type { Capabilities, Decision, Exposure, JsonValue, ReleaseContext, ReleaseState, Signal, SignalKind } from './types.js';
+import type { RegisterTargetOptions, RegisterTargetResult } from './adapter.js';
+export interface ExtensionResult {
+    readonly ok: boolean;
+    readonly error?: FireweaveError;
+    readonly degraded?: boolean;
+}
+/**
+ * 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): 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;
+}
+/**
+ * Exposure recording, with the browser's defining constraint: a tab can vanish
+ * without warning. Queued exposures are therefore flushed on
+ * `visibilitychange → hidden` and on `pagehide`, over a transport that survives
+ * unload. There is no server analogue for this — a server process gets a
+ * shutdown hook; a tab gets nothing.
+ */
+export declare class WebExposuresApi {
+    private readonly runtime;
+    private readonly seen;
+    private detach;
+    constructor(runtime: FireweaveWebRuntime);
+    /** Record one exposure. Deduped per (flagKey, targetingKey, variant). */
+    record(exposure: Exposure): ExtensionResult;
+    flush(): Promise<ExtensionResult>;
+    /**
+     * Attach unload-time flushing. Idempotent; returns a detach function.
+     *
+     * `visibilitychange → hidden` fires in cases `pagehide` does not (tab switch
+     * on mobile, app backgrounded) and vice versa (bfcache navigation), so both
+     * are needed. `beforeunload` is deliberately not used: it suppresses bfcache.
+     */
+    attachUnloadFlush(): () => void;
+}
+declare const DEFAULT_SIGNAL_ATTRIBUTE_ALLOWLIST: readonly string[];
+export declare class WebSignalsApi {
+    private readonly runtime;
+    private readonly recorded;
+    constructor(runtime: FireweaveWebRuntime);
+    private send;
+    recordHealth(signal: Omit<Signal, 'kind'>): ExtensionResult;
+    recordError(signal: Omit<Signal, 'kind'>): ExtensionResult;
+    recordMetric(signal: Omit<Signal, 'kind'>): ExtensionResult;
+    recordOutcome(signal: Omit<Signal, 'kind'>): ExtensionResult;
+    getRecorded(kind?: SignalKind): readonly Signal[];
+}
+export interface ReleaseResult extends ExtensionResult {
+    readonly state?: ReleaseState;
+}
+/**
+ * Release lifecycle from the browser.
+ *
+ * `setContext` is the load-bearing member — it stamps every subsequent exposure
+ * and signal with the rollout it belongs to. `start`/`complete`/`fail` exist
+ * for parity with the server client; a browser is rarely the thing that decides
+ * a release transitioned, so they are recorded as signals rather than pretending
+ * to drive state the backend owns.
+ */
+export declare class WebReleasesApi {
+    private readonly runtime;
+    private readonly signals;
+    private state;
+    constructor(runtime: FireweaveWebRuntime, signals: WebSignalsApi);
+    setContext(context: ReleaseContext): ExtensionResult;
+    private transition;
+    start(): ReleaseResult;
+    complete(): ReleaseResult;
+    fail(): ReleaseResult;
+    getState(): ReleaseState;
+}
+/** Phase-one stub: every method degrades with UnsupportedCapability. */
+declare class WebGuardrailsApi {
+    evaluate(_name: string, _args?: Record<string, JsonValue>): ExtensionResult;
+}
+declare class WebCapabilitiesApi {
+    private readonly runtime;
+    constructor(runtime: FireweaveWebRuntime);
+    list(): readonly string[];
+    get(): Capabilities;
+}
+export interface FireweaveWebClientOptions {
+    /** Attach unload-time exposure flushing on construction. Default true. */
+    readonly autoFlushOnUnload?: boolean;
+}
+export declare class FireweaveWebClient {
+    readonly runtime: FireweaveWebRuntime;
+    readonly controlPoints: WebControlPointsApi;
+    readonly exposures: WebExposuresApi;
+    readonly signals: WebSignalsApi;
+    readonly releases: WebReleasesApi;
+    readonly guardrails: WebGuardrailsApi;
+    readonly capabilities: WebCapabilitiesApi;
+    constructor(runtime: FireweaveWebRuntime, options?: FireweaveWebClientOptions);
+    /** Dynamic capability dispatch. Unknown capabilities degrade; never throws. */
+    invokeCapability(capability: string, _args?: Record<string, JsonValue>): ExtensionResult;
+    initialize(context?: ContextInput): Promise<void>;
+    /**
+     * 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>;
+}
+export { DEFAULT_SIGNAL_ATTRIBUTE_ALLOWLIST };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+import type { CanonicalContext } from './types.js';
+export interface ContextLimits {
+    readonly maxAttributeCount: number;
+    readonly maxKeyBytes: number;
+    readonly maxValueBytes: number;
+    readonly maxSerializedBytes: number;
+    readonly maxNestingDepth: number;
+}
+export declare const DEFAULT_CONTEXT_LIMITS: ContextLimits;
+/**
+ * Keys the backend owns. A client that could set these could claim another
+ * tenant's identity, so they are rejected rather than dropped — silently
+ * discarding them would leave the caller believing targeting was applied.
+ */
+export declare const DEFAULT_RESERVED_ATTRIBUTE_KEYS: readonly string[];
+export type ContextInput = Record<string, unknown> & {
+    targetingKey?: string;
+};
+/** Later contexts win, key by key. Mirrors the OpenFeature merge order. */
+export declare function mergeContexts(...contexts: ReadonlyArray<ContextInput | undefined>): ContextInput;
+/**
+ * Validate and canonicalize. Throws `FireweaveError('InvalidContext')` on any
+ * limit breach or reserved-key use; never mutates the input.
+ */
+export declare function canonicalizeContext(input: ContextInput | undefined, limits?: ContextLimits, reservedKeys?: readonly string[]): CanonicalContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,eAAO,MAAM,sBAAsB,EAAE,aAMnC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,SAAS,MAAM,EAI3D,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAiB/E,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,aAAa,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,YAAY,CAOhG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,MAAM,GAAE,aAAsC,EAC9C,YAAY,GAAE,SAAS,MAAM,EAAoC,GAChE,gBAAgB,CA6ClB"}

package/dist/context.js

@@ -0,0 +1,106 @@
+/**
+ * Evaluation-context normalization.
+ *
+ * A browser context is smaller than a server one — there is one user per page,
+ * not one per request — but the same two rules apply, and for the same reasons:
+ * reserved keys cannot be spoofed by the caller, and oversized attributes are
+ * rejected rather than silently truncated by the backend.
+ *
+ * UTF-8 byte length is measured with `TextEncoder`, never `Buffer` — the same
+ * choice ADR-0008 made in the server SDK, here because `Buffer` does not exist
+ * in a browser at all.
+ */
+import { FireweaveError } from './errors.js';
+export const DEFAULT_CONTEXT_LIMITS = Object.freeze({
+    maxAttributeCount: 100,
+    maxKeyBytes: 256,
+    maxValueBytes: 8_192,
+    maxSerializedBytes: 32_768,
+    maxNestingDepth: 8,
+});
+/**
+ * Keys the backend owns. A client that could set these could claim another
+ * tenant's identity, so they are rejected rather than dropped — silently
+ * discarding them would leave the caller believing targeting was applied.
+ */
+export const DEFAULT_RESERVED_ATTRIBUTE_KEYS = Object.freeze([
+    'fireweave.orgId',
+    'fireweave.projectId',
+    'fireweave.tenant',
+]);
+const encoder = new TextEncoder();
+function byteLength(value) {
+    return encoder.encode(value).length;
+}
+function depthOf(value, depth = 0) {
+    if (value === null || typeof value !== 'object')
+        return depth;
+    let deepest = depth;
+    for (const child of Object.values(value)) {
+        deepest = Math.max(deepest, depthOf(child, depth + 1));
+    }
+    return deepest;
+}
+/** Later contexts win, key by key. Mirrors the OpenFeature merge order. */
+export function mergeContexts(...contexts) {
+    const merged = {};
+    for (const ctx of contexts) {
+        if (ctx === undefined)
+            continue;
+        Object.assign(merged, ctx);
+    }
+    return merged;
+}
+/**
+ * Validate and canonicalize. Throws `FireweaveError('InvalidContext')` on any
+ * limit breach or reserved-key use; never mutates the input.
+ */
+export function canonicalizeContext(input, limits = DEFAULT_CONTEXT_LIMITS, reservedKeys = DEFAULT_RESERVED_ATTRIBUTE_KEYS) {
+    const source = input ?? {};
+    const attributes = {};
+    let groups;
+    let groupProperties;
+    let targetingKey;
+    for (const [key, value] of Object.entries(source)) {
+        if (key === 'targetingKey') {
+            if (typeof value === 'string' && value.length > 0)
+                targetingKey = value;
+            continue;
+        }
+        if (reservedKeys.includes(key)) {
+            throw new FireweaveError('InvalidContext');
+        }
+        if (key === 'groups' || key === 'fireweave.groups') {
+            groups = value;
+            continue;
+        }
+        if (key === 'groupProperties' || key === 'fireweave.groupProperties') {
+            groupProperties = value;
+            continue;
+        }
+        if (value === undefined)
+            continue;
+        if (byteLength(key) > limits.maxKeyBytes)
+            throw new FireweaveError('InvalidContext');
+        const serialized = JSON.stringify(value) ?? 'null';
+        if (byteLength(serialized) > limits.maxValueBytes)
+            throw new FireweaveError('InvalidContext');
+        if (depthOf(value) > limits.maxNestingDepth)
+            throw new FireweaveError('InvalidContext');
+        attributes[key] = value;
+    }
+    if (Object.keys(attributes).length > limits.maxAttributeCount) {
+        throw new FireweaveError('InvalidContext');
+    }
+    if (byteLength(JSON.stringify(attributes)) > limits.maxSerializedBytes) {
+        throw new FireweaveError('InvalidContext');
+    }
+    const canonical = { attributes };
+    return {
+        ...canonical,
+        ...(targetingKey !== undefined ? { targetingKey } : {}),
+        ...(groups !== undefined ? { groups } : {}),
+        ...(groupProperties !== undefined ? { groupProperties } : {}),
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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