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

package/dist/domain/errors.js

@@ -1,97 +0,0 @@
-"use strict";
-/**
- * Error taxonomy for the browser SDK.
- *
- * Same kinds and same OpenFeature mapping as the server SDK, because the wire
- * protocol and the failure modes are the same — a 401 is a 401 whether it is a
- * server or a browser asking. Reimplemented here rather than shared so the
- * browser package keeps zero cross-package coupling and can be audited on its
- * own; `spec/errors.schema.json` is the source both follow.
- *
- * Messages are FIXED per kind. A browser error is visible in a devtools console
- * on a machine we do not control, so nothing host-, key-, or response-derived
- * is ever interpolated into one.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FireweaveError = exports.ERROR_TAXONOMY = void 0;
-exports.isFireweaveError = isFireweaveError;
-exports.ERROR_TAXONOMY = Object.freeze({
-    Configuration: {
-        message: 'invalid configuration',
-        openFeatureErrorCode: 'PROVIDER_FATAL',
-        retryable: false,
-    },
-    Authentication: {
-        message: 'authentication failed',
-        openFeatureErrorCode: 'PROVIDER_FATAL',
-        retryable: false,
-    },
-    Authorization: {
-        message: 'not authorized',
-        openFeatureErrorCode: 'PROVIDER_FATAL',
-        retryable: false,
-    },
-    Network: { message: 'network error', openFeatureErrorCode: 'GENERAL', retryable: true },
-    Timeout: { message: 'request timed out', openFeatureErrorCode: 'GENERAL', retryable: true },
-    RateLimited: { message: 'rate limited', openFeatureErrorCode: 'GENERAL', retryable: true },
-    BackendUnavailable: {
-        message: 'backend unavailable',
-        openFeatureErrorCode: 'GENERAL',
-        retryable: true,
-    },
-    MalformedResponse: {
-        message: 'malformed response',
-        openFeatureErrorCode: 'PARSE_ERROR',
-        retryable: false,
-    },
-    InvalidContext: {
-        message: 'invalid evaluation context',
-        openFeatureErrorCode: 'INVALID_CONTEXT',
-        retryable: false,
-    },
-    ControlPointNotFound: {
-        message: 'flag not found',
-        openFeatureErrorCode: 'FLAG_NOT_FOUND',
-        retryable: false,
-    },
-    TypeMismatch: {
-        message: 'type mismatch',
-        openFeatureErrorCode: 'TYPE_MISMATCH',
-        retryable: false,
-    },
-    NotReady: {
-        message: 'provider not ready',
-        openFeatureErrorCode: 'PROVIDER_NOT_READY',
-        retryable: true,
-    },
-    AlreadyClosed: {
-        message: 'provider already closed',
-        openFeatureErrorCode: 'PROVIDER_FATAL',
-        retryable: false,
-    },
-    UnsupportedCapability: {
-        message: 'unsupported capability',
-        openFeatureErrorCode: 'GENERAL',
-        retryable: false,
-    },
-    Internal: { message: 'internal error', openFeatureErrorCode: 'GENERAL', retryable: false },
-});
-class FireweaveError extends Error {
-    kind;
-    openFeatureErrorCode;
-    retryable;
-    metadata;
-    constructor(kind, options = {}) {
-        const spec = exports.ERROR_TAXONOMY[kind];
-        super(spec.message, options.cause !== undefined ? { cause: options.cause } : undefined);
-        this.name = 'FireweaveError';
-        this.kind = kind;
-        this.openFeatureErrorCode = options.openFeatureErrorCode ?? spec.openFeatureErrorCode;
-        this.retryable = spec.retryable;
-        this.metadata = { ...(options.metadata ?? {}) };
-    }
-}
-exports.FireweaveError = FireweaveError;
-function isFireweaveError(value) {
-    return value instanceof FireweaveError;
-}

package/dist/domain/target.d.ts

@@ -1,2 +0,0 @@
-/** What is being registered — see spec/remote-register-target.schema.json. */
-export type TargetKind = 'user' | 'device';

package/dist/domain/target.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/types.d.ts

@@ -1,89 +0,0 @@
-/**
- * Canonical data shapes, mirroring `spec/decision.schema.json`,
- * `spec/signal.schema.json`, and `spec/release-context.schema.json`.
- *
- * Identical in meaning to the server SDK's `types.ts`. Duplicated rather than
- * shared so the browser package has no cross-package dependency to audit; the
- * JSON Schemas in `spec/` are what keep the two honest.
- */
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-export type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
-export type DecisionReason = 'STATIC' | 'DEFAULT' | 'TARGETING_MATCH' | 'SPLIT' | 'CACHED' | 'STALE' | 'DISABLED' | 'UNKNOWN' | 'ERROR';
-export interface Decision {
-    readonly controlPointKey: string;
-    readonly value: JsonValue;
-    readonly reason: DecisionReason;
-    readonly variant?: string;
-    readonly errorCode?: string;
-    readonly errorKind?: string;
-    readonly errorMessage?: string;
-    readonly metadata?: Record<string, string | number | boolean>;
-}
-/**
- * A browser lifecycle has one state the server does not: STALE.
- *
- * It means "initialize completed, but the prefetch did not, so reads are being
- * served from an empty or outdated cache". Collapsing it into READY would make
- * a failed boot indistinguishable from a successful one — which is the specific
- * failure this SDK is written to avoid.
- */
-export type LifecycleState = 'UNINITIALIZED' | 'INITIALIZING' | 'READY' | 'STALE' | 'ERROR' | 'SHUTDOWN';
-export interface CanonicalContext {
-    readonly targetingKey?: string;
-    readonly attributes: Record<string, JsonValue>;
-    readonly groups?: Record<string, string>;
-    readonly groupProperties?: Record<string, Record<string, JsonValue>>;
-}
-export type SignalKind = 'health' | 'error' | 'metric' | 'outcome';
-export interface Signal {
-    readonly kind: SignalKind;
-    readonly name: string;
-    readonly targetingKey?: string;
-    readonly controlPointKey?: string;
-    readonly variant?: string;
-    readonly status?: string;
-    readonly errorKind?: string;
-    readonly message?: string;
-    readonly value?: number;
-    readonly rolloutId?: string;
-    readonly changeId?: string;
-    readonly stampId?: string;
-    readonly timestamp?: string;
-}
-export interface Exposure {
-    readonly controlPointKey: string;
-    readonly targetingKey: string;
-    readonly value: JsonValue;
-    readonly variant?: string;
-    readonly rolloutId?: string;
-    readonly changeId?: string;
-    readonly stampId?: string;
-}
-export type ReleaseState = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED';
-export interface ReleaseContext {
-    readonly rolloutId?: string;
-    readonly changeId?: string;
-    readonly stampId?: string;
-    readonly environment?: string;
-}
-export interface Capabilities {
-    readonly static: {
-        readonly language: 'web';
-        readonly sdkVersion: string;
-        readonly specVersion: string;
-        readonly openFeature: {
-            readonly specFloor: string;
-            readonly providerName: string;
-            readonly serverOnly: boolean;
-        };
-        readonly features: Record<string, boolean>;
-    };
-    readonly runtime: {
-        readonly backend: 'fireweave' | 'inmemory' | 'none' | 'other';
-        readonly lifecycle: LifecycleState;
-        readonly features: Record<string, boolean>;
-        readonly limits: Record<string, number>;
-    };
-}

package/dist/domain/types.js

@@ -1,10 +0,0 @@
-"use strict";
-/**
- * Canonical data shapes, mirroring `spec/decision.schema.json`,
- * `spec/signal.schema.json`, and `spec/release-context.schema.json`.
- *
- * Identical in meaning to the server SDK's `types.ts`. Duplicated rather than
- * shared so the browser package has no cross-package dependency to audit; the
- * JSON Schemas in `spec/` are what keep the two honest.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/validation.d.ts

@@ -1,128 +0,0 @@
-/**
- * Fireweave web SDK validation — pure, total functions per
- * spec/control-points.md "Validation, before any I/O" and spec/modes.md
- * "Initialisation validation".
- *
- * Ported from sdks/node/src/domain/validation.ts (the reference
- * implementation) — same five validators, same `Validated<T>` discipline,
- * same malformed-key → ControlPointNotFound mapping. Reimplemented here rather than
- * shared so the browser package keeps zero cross-package dependency to
- * audit — the same reasoning ADR-0009 gives for duplicating types.ts/errors.ts
- * extends to this module.
- *
- * Every read-path validator here (`validateControlPointKey`,
- * `validateDefaultValue`, `validateContext`) returns `Validated<T>` instead
- * of throwing. `FireweaveWebRuntime.evaluateSync` runs them, in the fixed
- * order the spec names — key, default-vs-type, context, lifecycle — and
- * degrades to the caller's default on the first failure; it NEVER throws
- * (spec/control-points.md "Return discipline — never throw into a read
- * path"). `validateInitOptions` is the one exception (spec/modes.md
- * "Initialisation validation"): it still returns `Validated<T>` — mode.ts is
- * what converts a failed result into the throw spec/modes.md requires.
- *
- * Note: unlike node, web's `FireweaveError` has no custom-message support —
- * messages are FIXED per kind by design, because a browser error is visible
- * in a devtools console on a machine this package does not control
- * (errors.ts's own doc comment). So every branch below that would carry a
- * distinct node message instead just uses the taxonomy's fixed message for
- * its kind.
- */
-import { FireweaveError } from './errors.js';
-import type { ContextPolicy } from './context.js';
-import type { CanonicalContext, JsonValue } from './types.js';
-/** Result of a pure validator: success carries the validated value, failure the canonical error. */
-export type Validated<T> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: FireweaveError;
-};
-/**
- * key — non-empty, ≤256 characters, no control characters
- * (spec/control-points.md rule 1, the first check in the fixed order).
- *
- * No taxonomy kind names "malformed key" explicitly (the return-discipline
- * table's closest row is "key unknown to the backend" → ControlPointNotFound):
- * controller-ruled interim mapping (mirrors node's domain/validation.ts
- * verbatim) — the 15-kind taxonomy in errors.schema.json is frozen at
- * exactly 15 entries, `InvalidContext` is textually scoped to the evaluation
- * *context* (not the key), and the schema already maps another non-literal
- * case — quota-limited responses — onto `ControlPointNotFound` rather than adding a
- * kind for it. `ControlPointNotFound` is therefore the least-wrong existing kind,
- * not a literal fit. Other-language implementations copying node as the
- * reference SHOULD use the same mapping rather than each independently
- * guessing a different one.
- */
-export declare function validateControlPointKey(key: string): Validated<string>;
-export type ExpectedFlagType = 'boolean' | 'string' | 'number' | 'object';
-/**
- * Whether `value` matches the shape `expected` names. Shared by
- * {@link validateDefaultValue} (the caller's default, before any read) and
- * `FireweaveWebRuntime.evaluateSync`'s post-cache-lookup check (the backend's
- * resolved value, from the prefetched cache) — same predicate, two different
- * inputs.
- */
-export declare function matchesExpectedType(value: JsonValue | undefined, expected: ExpectedFlagType): boolean;
-/**
- * default vs type — e.g. `getBooleanValue` with a non-boolean default is
- * TypeMismatch (spec/control-points.md rule 2, checked before any read).
- */
-export declare function validateDefaultValue(expectedType: ExpectedFlagType, defaultValue: JsonValue): Validated<JsonValue>;
-/**
- * targetingKey: "An SDK MUST NOT invent one: a missing targeting key is
- * InvalidContext where the evaluation needs it, never a generated anonymous
- * id" (spec/control-points.md "Context"). `required` is call-site policy —
- * the remote adapter always requires one for `prefetch`/`registerTarget`; the
- * generic context pipeline ({@link validateContext}) only does when
- * `ContextPolicy.requireTargetingKey` opts in (unset by default here — web's
- * targetingKey requirement is enforced at the remote adapter, not the
- * general-purpose context validator every read runs).
- */
-export declare function validateTargetingKey(targetingKey: string | undefined, required: boolean): Validated<string | undefined>;
-/**
- * context — depth, key count, value size, reserved keys
- * (evaluation-context.schema.json) (spec/control-points.md rule 3). Also
- * enforces `policy.requireTargetingKey` via {@link validateTargetingKey}, and
- * — on success — extracts `groups`/`groupProperties` the same way the former
- * `canonicalizeContext` did.
- *
- * `groups`/`groupProperties` (and their `fireweave.*` aliases) are pulled out
- * BEFORE the attribute-count/size limit checks run, matching the pre-existing
- * behaviour this module replaces: they are not ordinary attributes and were
- * never counted against those limits.
- *
- * `merged` is the already-merged (global → invocation) raw input; merging
- * itself (`mergeContexts`) lives in context.ts and carries no validation
- * concerns of its own.
- */
-export declare function validateContext(merged: {
-    targetingKey?: string;
-    attributes: Record<string, unknown>;
-}, policy: ContextPolicy): Validated<CanonicalContext>;
-/**
- * Throwing wrapper around {@link validateContext}, kept for callers that
- * genuinely want a throw (`FireweaveWebRuntime.refresh`, which is already
- * inside its own try/catch feeding lifecycle state — see runtime.ts). Read
- * paths do not use this — they call {@link validateContext} directly so a
- * failure degrades instead of throwing.
- */
-export declare function canonicalizeContext(merged: {
-    targetingKey?: string;
-    attributes: Record<string, unknown>;
-}, policy: ContextPolicy): CanonicalContext;
-/**
- * Initialisation-validation table (spec/modes.md), rows 1, 2 and 4:
- *  - `mode` absent or unrecognised
- *  - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
- *  - `mode: 'local'` with credentials supplied (a config half-migrated from
- *    remote to local reads as neither, silently — reject it instead)
- *
- * Row 3 ("apiUrl fails the host allowlist") is intentionally NOT checked
- * here — mode.ts validates it directly via `assertHostAllowed` before
- * calling into the (deliberately non-throwing) runtime; see mode.ts's module
- * doc comment for why web cannot rely on the runtime the way node does.
- */
-export declare function validateInitOptions<T extends {
-    readonly mode?: unknown;
-}>(options: T): Validated<T>;