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

package/dist/domain/errors.js

@@ -1,99 +0,0 @@
-"use strict";
-/**
- * Fireweave canonical error taxonomy (spec/errors.schema.json, contracts/errors.json).
- *
- * 15 PascalCase kinds mapped to OpenFeature error codes. Rules:
- *  - defaults never throw: evaluation paths surface errors via Decision, not exceptions;
- *  - no secrets in messages: all outward-facing messages are redacted;
- *  - cause preserved internally (`FireweaveError.cause`), never serialized outward.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FireweaveError = exports.ERROR_TAXONOMY = void 0;
-exports.redactSecrets = redactSecrets;
-exports.isFireweaveError = isFireweaveError;
-const spec = (kind, openFeatureErrorCode, retryable, errorClass, defaultMessage) => ({ kind, openFeatureErrorCode, retryable, errorClass, defaultMessage });
-exports.ERROR_TAXONOMY = Object.freeze({
-    NotReady: spec('NotReady', 'PROVIDER_NOT_READY', true, 'transient', 'provider not ready'),
-    ControlPointNotFound: spec('ControlPointNotFound', 'FLAG_NOT_FOUND', false, 'permanent', 'flag not found'),
-    TypeMismatch: spec('TypeMismatch', 'TYPE_MISMATCH', false, 'permanent', 'flag type mismatch'),
-    InvalidContext: spec('InvalidContext', 'INVALID_CONTEXT', false, 'permanent', 'invalid evaluation context'),
-    Authentication: spec('Authentication', 'GENERAL', false, 'permanent', 'authentication failed'),
-    Authorization: spec('Authorization', 'GENERAL', false, 'permanent', 'authorization failed'),
-    RateLimited: spec('RateLimited', 'GENERAL', true, 'transient', 'rate limited'),
-    Timeout: spec('Timeout', 'GENERAL', true, 'transient', 'request timed out'),
-    Network: spec('Network', 'GENERAL', true, 'transient', 'network error'),
-    BackendUnavailable: spec('BackendUnavailable', 'GENERAL', true, 'transient', 'backend unavailable'),
-    MalformedResponse: spec('MalformedResponse', 'PARSE_ERROR', false, 'permanent', 'malformed backend response'),
-    UnsupportedCapability: spec('UnsupportedCapability', 'GENERAL', false, 'permanent', 'unsupported capability'),
-    Configuration: spec('Configuration', 'PROVIDER_FATAL', false, 'permanent', 'invalid configuration'),
-    AlreadyClosed: spec('AlreadyClosed', 'PROVIDER_NOT_READY', false, 'permanent', 'provider already closed'),
-    Internal: spec('Internal', 'GENERAL', false, 'permanent', 'internal error'),
-});
-/**
- * The redaction contract (contracts/errors.json `rules.redaction`, start-profile
- * SP-26). Applied in this order: bearer tokens, URL userinfo, named
- * assignments, then key-shaped values. A variable NAME is never redacted on its
- * own; only its value is. `test/unit/redaction-contract.test.ts` runs every
- * contract vector through `redactSecrets`.
- */
-const REDACTION_PLACEHOLDER = '[REDACTED]';
-/** Variables whose assigned value is scrubbed: `NAME=value`, `NAME: value`, `NAME = "value"`. */
-const ASSIGNMENT_NAMES = ['FIREWEAVE_KEY', 'FIREWEAVE_BROWSER_KEY', 'FW_PROJECT_API_KEY'];
-/** Key families; a prefix only counts when one or more of [A-Za-z0-9_-] follows it. */
-const VALUE_PREFIXES = [
-    'project-api-key_',
-    'fw_public_',
-    'fw_ingest_pub_',
-    'fw_org_',
-    'cli_at_',
-    'phc_',
-    'phx_',
-    'phs_',
-];
-const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-const BEARER = /\bBearer(\s+)[A-Za-z0-9._~+/=-]+/g;
-// scheme://userinfo@host: userinfo cannot hold whitespace, '/', '?', '#' or '@'.
-const URL_USERINFO = /\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^\s/?#@]+@/g;
-// The name stays, as do the separator and any opening quote; the value runs to
-// whitespace, a quote, a comma or a semicolon. The lookbehind keeps a longer
-// name that merely ends in one of these (MY_FIREWEAVE_KEY) out of scope.
-const ASSIGNMENT = new RegExp(`(?<![A-Za-z0-9_])(${ASSIGNMENT_NAMES.map(escapeRegExp).join('|')})(\\s*[=:]\\s*)(["']?)[^\\s"',;]+`, 'g');
-// No leading boundary: a key glued to other text is still a key.
-const KEY_VALUE = new RegExp(`(?:${VALUE_PREFIXES.map(escapeRegExp).join('|')})[A-Za-z0-9_-]+`, 'g');
-/**
- * Scrub secrets per the redaction contract, then collapse whitespace runs and
- * trim (so a message stays on one log line).
- */
-function redactSecrets(text) {
-    const out = text
-        .replace(BEARER, `Bearer$1${REDACTION_PLACEHOLDER}`)
-        .replace(URL_USERINFO, `$1${REDACTION_PLACEHOLDER}@`)
-        .replace(ASSIGNMENT, `$1$2$3${REDACTION_PLACEHOLDER}`)
-        .replace(KEY_VALUE, REDACTION_PLACEHOLDER);
-    return out.replace(/\s+/g, ' ').trim();
-}
-class FireweaveError extends Error {
-    kind;
-    openFeatureErrorCode;
-    retryable;
-    errorClass;
-    /** Deterministic outward-facing message from the taxonomy. */
-    safeMessage;
-    metadata;
-    constructor(kind, options = {}) {
-        const taxonomy = exports.ERROR_TAXONOMY[kind];
-        const message = options.message !== undefined ? redactSecrets(options.message) : taxonomy.defaultMessage;
-        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
-        this.name = 'FireweaveError';
-        this.kind = kind;
-        this.openFeatureErrorCode = options.openFeatureErrorCode ?? taxonomy.openFeatureErrorCode;
-        this.retryable = taxonomy.retryable;
-        this.errorClass = taxonomy.errorClass;
-        this.safeMessage = taxonomy.defaultMessage;
-        this.metadata = Object.freeze({ ...(options.metadata ?? {}) });
-    }
-}
-exports.FireweaveError = FireweaveError;
-function isFireweaveError(err) {
-    return err 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,107 +0,0 @@
-import type { FireweaveErrorKind, OpenFeatureErrorCode } from './errors.js';
-/** JSON-compatible value (spec/decision.schema.json `value`). */
-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';
-/** Canonical decision (spec/decision.schema.json). */
-export interface Decision {
-    controlPointKey: string;
-    value: JsonValue;
-    reason: DecisionReason;
-    variant?: string;
-    errorCode?: OpenFeatureErrorCode;
-    errorKind?: FireweaveErrorKind;
-    errorMessage?: string;
-    /** fireweave.* flag metadata surfaced to OpenFeature controlPointMetadata. */
-    metadata: Record<string, string | number | boolean>;
-}
-/** Canonical evaluation context after validation/canonicalization. */
-export interface CanonicalContext {
-    targetingKey?: string;
-    /** All non-reserved attributes (targetingKey excluded). */
-    attributes: Record<string, JsonValue>;
-    /**
-     * Group memberships extracted from `fireweave.groups` (canonical, ruling 13)
-     * or the plain `groups` alias, when shaped as Record<string,string>.
-     */
-    groups?: Record<string, string>;
-    /**
-     * Group properties extracted from `fireweave.groupProperties` (canonical)
-     * or the plain `groupProperties` alias.
-     */
-    groupProperties?: Record<string, JsonValue>;
-}
-export type LifecycleState = 'UNINITIALIZED' | 'INITIALIZING' | 'READY' | 'STALE' | 'ERROR' | 'FATAL' | 'SHUTDOWN';
-export type SignalKind = 'health' | 'error' | 'metric' | 'outcome';
-/** Canonical signal envelope (spec/signal.schema.json). */
-export interface Signal {
-    kind: SignalKind;
-    name: string;
-    status?: string;
-    errorKind?: FireweaveErrorKind;
-    message?: string;
-    value?: number | boolean | string;
-    timestamp?: string;
-    targetingKey?: string;
-    rolloutId?: string;
-    changeId?: string;
-    stampId?: string;
-    controlPointKey?: string;
-    variant?: string;
-    traceId?: string;
-    role?: 'adoption' | 'guard' | 'quality' | 'custom';
-    direction?: 'up-good' | 'up-bad' | 'neutral';
-    attributes?: Record<string, string | number | boolean | null>;
-}
-/** Release / rollout context (spec/release-context.schema.json; ruling 15: rolloutId + stampIds required). */
-export interface ReleaseContext {
-    stampIds: string[];
-    rolloutId: string;
-    changeId?: string;
-    surfaces?: Array<{
-        surfaceId: string;
-        kind?: 'ts-server' | 'node-server' | 'python' | 'go' | 'java' | 'web' | 'other';
-    }>;
-    metadata?: Record<string, string | number | boolean>;
-}
-export type ReleaseStatus = 'set' | 'in_progress' | 'completed' | 'failed';
-export interface ReleaseState {
-    context: ReleaseContext;
-    status: ReleaseStatus;
-    reason?: string;
-}
-/** Exposure event (extensions fixtures shape). */
-export interface Exposure {
-    targetingKey: string;
-    controlPointKey: string;
-    value: JsonValue;
-    variant?: string;
-    rolloutId?: string;
-    changeId?: string;
-    stampId?: string;
-}
-/** Capability matrix (spec/capabilities.schema.json). */
-export interface Capabilities {
-    static: {
-        language: 'node';
-        sdkVersion?: string;
-        specVersion?: '0.1.0';
-        openFeature: {
-            specFloor: '0.8.0';
-            providerName: 'fireweave';
-            serverOnly?: boolean;
-        };
-        features: Record<string, boolean>;
-    };
-    runtime: {
-        backend: 'fireweave' | 'inmemory' | 'none' | 'other';
-        lifecycle: LifecycleState;
-        features?: Record<string, boolean>;
-        limits?: {
-            intSafeMaxAbs?: number;
-            shutdownTimeoutMsDefault?: number;
-        };
-    };
-}

package/dist/domain/types.js

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

package/dist/domain/validation.d.ts

@@ -1,124 +0,0 @@
-/**
- * Fireweave SDK validation — pure, total functions per spec/control-points.md
- * "Validation, before any I/O" and spec/modes.md "Initialisation validation".
- *
- * Every read-path validator here (`validateControlPointKey`,
- * `validateDefaultValue`, `validateContext`, `validateTargetingKey`) returns
- * `Validated<T>` instead of throwing. `FireweaveRuntime.evaluate` 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 named exception (spec/modes.md
- * "Initialisation validation"): its failures are converted to a THROW by
- * `initFireweave` (src/init.ts). The validator itself still returns
- * `Validated<T>` — the entry point does the throwing, not this module.
- *
- * Collected into one module so it can move wholesale into `domain/` (plan
- * Phase 1.4) without touching its exports or call sites again. Everything
- * below is pure (no I/O, no ambient state) and total (every branch returns a
- * `Validated<T>`) — `conformance/` can exercise all four read-path rules
- * offline, with no backend.
- *
- * `validateInitOptions` is deliberately generic rather than importing
- * `InitFireweaveOptions` from `init.ts`: init.ts is the "mode" entry point
- * (Phase 1.4 assigns it to `application/`), and this module is destined for
- * `domain/`, which must not depend on outer layers. It also does not
- * validate "apiUrl fails the host allowlist" (spec/modes.md row 3) — that
- * check (`assertHostAllowed`) lives in `hosts.ts`, which Phase 1.4 assigns to
- * `infrastructure/`; it stays reachable today via `FireweaveRuntime.initialize`
- * (runtime.ts) / `FireweaveRemoteAdapter.initialize` (adapters/remote.ts),
- * unchanged by this module.
- */
-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): a key
- * that can never identify a flag is treated the same as one the backend
- * doesn't recognise, so this maps to ControlPointNotFound too.
- *
- * Controller-ruled interim mapping (Task 3 review): 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 I/O) and
- * `FireweaveRuntime.evaluate`'s post-resolve check (the backend's resolved
- * value, after I/O) — same predicate, two different inputs.
- */
-export declare function matchesExpectedType(value: JsonValue, 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 I/O).
- */
-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 `resolve`/`registerTarget`
- * (spec/remote-protocol.md "Two identity paths"); the generic context
- * pipeline ({@link validateContext}) only does when
- * `ContextPolicy.requireTargetingKey` opts in.
- */
-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.
- *
- * `merged` is the already-merged (global → client → 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 the pre-existing
- * public surface (`FireweaveRuntime.resolveContext`, direct callers of the
- * package export). 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 — see the module doc comment.
- */
-export declare function validateInitOptions<T extends {
-    readonly mode?: unknown;
-}>(options: T): Validated<T>;