@ops-ai/react-router-toggly 1.0.0

package/dist/client.d.cts

@@ -0,0 +1,603 @@
+import { LocalGate } from '@ops-ai/toggly-local-gates';
+import { EvaluatedDefinitions, TogglyEntityContext } from '@ops-ai/toggly-hooks-types';
+export { TogglyEntityContext, normalizeEntityContext, registerContext } from '@ops-ai/toggly-hooks-types';
+import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
+
+interface UsageSender {
+    sendStats(request: Record<string, unknown>): Promise<unknown>;
+    close?(): void;
+}
+interface MetricsSender {
+    sendMetrics(request: Record<string, unknown>): Promise<unknown>;
+    close?(): void;
+}
+
+/**
+ * Feature requirement - whether all or any features must be enabled
+ */
+type FeatureRequirement = 'all' | 'any';
+/**
+ * Where feature evaluation happens for definitions fetches.
+ * - `remote` (default): fetch `evaluated-signed` with context query params
+ * - `local`: fetch `definitions-signed` (rules only) and evaluate with `@ops-ai/toggly-eval`
+ */
+type EvaluationMode = 'local' | 'remote';
+/**
+ * Configuration options for Toggly
+ */
+interface TogglyConfig {
+    /** Toggly application key */
+    appKey?: string;
+    /** Environment name (e.g., 'Production', 'Staging') */
+    environment?: string;
+    /** Base URL for Toggly API */
+    baseUrl?: string;
+    /**
+     * Evaluation rail. Defaults to `remote` for backward compatibility.
+     * Use `local` for definitions-signed + call-site evaluation (server multi-tenant).
+     */
+    evaluationMode?: EvaluationMode;
+    /** Default feature values for offline/fallback mode */
+    featureDefaults?: Record<string, boolean>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * When true, verify ES256 signed definition envelopes via JWKS before applying flags.
+     */
+    verifySignatures?: boolean;
+    /**
+     * Optional allow-list of JWKS `kid` values when verifySignatures is enabled.
+     */
+    allowedKeyIds?: string[];
+    /**
+     * Reject envelopes whose `timestamp` is older than this many seconds.
+     * Unset or <= 0 disables freshness checks.
+     */
+    maxSignatureAgeSeconds?: number;
+    /** Device-local gates applied as a read-time AND on worker-evaluated booleans */
+    localGates?: LocalGate[];
+    /** Optional SDK error callback for reporting fetch/evaluation failures. */
+    onError?: (message: string, error?: unknown) => void;
+    /** Initial browser identity; hydrated server identity takes precedence. */
+    identity?: string;
+    /** User groups for targeting */
+    groups?: string[];
+    /** Custom claims for targeting */
+    claims?: Record<string, string>;
+    /**
+     * Base URL for usage/metrics transport (default: https://app.toggly.io/).
+     * Separate from `baseUrl`, which is for definitions/JWKS.
+     */
+    metricsBaseUrl?: string;
+    /**
+     * Enable feature usage tracking (Usage.SendStats / api/usage/stats).
+     * Defaults to false in core; react-router-toggly server enables when appKey is set.
+     */
+    enableUsageTracking?: boolean;
+    /**
+     * Enable business metrics (Metrics.SendMetrics / api/metrics).
+     * Defaults to false in core; react-router-toggly server enables when appKey is set.
+     */
+    enableMetrics?: boolean;
+    /** Usage flush interval in ms (default: 60000). 0 disables the timer. */
+    usageFlushInterval?: number;
+    /** Metrics flush interval in ms (default: 60000). 0 disables the timer. */
+    metricsFlushInterval?: number;
+    /** Hostname/instance name reported with usage/metrics payloads. */
+    instanceName?: string;
+    /** Application version reported with usage payloads. */
+    appVersion?: string;
+    /**
+     * Telemetry transport when clients are not injected.
+     * Server should use `grpc` with injected clients; edge adapters use `https`.
+     */
+    telemetryTransport?: 'grpc' | 'https';
+    /**
+     * Attach Node process signal handlers for best-effort flush (default: true for grpc).
+     * Edge adapters must set false.
+     */
+    telemetryAttachProcessHandlers?: boolean;
+    /**
+     * Injected usage sender (gRPC stub or test double).
+     * @internal
+     */
+    usageClient?: UsageSender | null;
+    /**
+     * Injected metrics sender (gRPC stub or test double).
+     * @internal
+     */
+    metricsClient?: MetricsSender | null;
+    /** Optional fetch override for HTTPS telemetry (edge/tests). */
+    telemetryFetch?: typeof fetch;
+}
+/**
+ * User identity context for feature targeting
+ */
+interface IdentityContext {
+    /** Unique user identifier */
+    identity?: string;
+    /** User groups for targeting */
+    groups?: string[];
+    /** Custom traits for targeting */
+    traits?: Record<string, string | number | boolean>;
+    /** Custom claims for targeting */
+    claims?: Record<string, string>;
+    /** HTTP request segment fields (UA / Accept-Language / country) */
+    request?: {
+        userAgent?: string;
+        acceptLanguage?: string;
+        country?: string;
+    };
+}
+/**
+ * Feature flags state (boolean or entity gate per flag)
+ */
+type FeatureFlags = EvaluatedDefinitions;
+/**
+ * Feature evaluation result
+ */
+interface EvaluationResult {
+    /** Whether the feature(s) are enabled */
+    enabled: boolean;
+    /** The feature keys that were evaluated */
+    featureKeys: string[];
+    /** The requirement type used */
+    requirement: FeatureRequirement;
+    /** Whether the result was negated */
+    negated: boolean;
+}
+/**
+ * Server-side feature context passed to client
+ */
+interface ServerFeatureContext {
+    /** Pre-fetched feature flags */
+    flags: FeatureFlags;
+    /** User identity (if any) */
+    identity?: string;
+    /** App key (for client-side refresh) */
+    appKey?: string;
+    /** Environment */
+    environment?: string;
+    /** Timestamp when flags were fetched */
+    fetchedAt: number;
+}
+/**
+ * Hook metadata
+ */
+interface HookMetadata {
+    name: string;
+    version?: string;
+    description?: string;
+}
+/**
+ * Evaluation series data passed between before/after hooks
+ */
+interface EvaluationSeriesData {
+    [key: string]: unknown;
+}
+/**
+ * Identity series data passed between before/after hooks
+ */
+interface IdentitySeriesData {
+    [key: string]: unknown;
+}
+/**
+ * Hook interface for extending SDK behavior
+ */
+interface TogglyHook {
+    /** Get hook metadata */
+    getMetadata(): HookMetadata;
+    /** Called before feature evaluation */
+    beforeEvaluation?(flagKey: string, defaultValue?: boolean): Promise<EvaluationSeriesData | void> | EvaluationSeriesData | void;
+    /** Called after feature evaluation */
+    afterEvaluation?(flagKey: string, data: EvaluationSeriesData | void, result: boolean): Promise<void> | void;
+    /** Called before user identification */
+    beforeIdentify?(identity: string): Promise<IdentitySeriesData | void> | IdentitySeriesData | void;
+    /** Called after user identification */
+    afterIdentify?(identity: string, data: IdentitySeriesData | void): Promise<void> | void;
+    /** Called after feature flags are refreshed */
+    afterRefresh?(flags: FeatureFlags): Promise<void> | void;
+}
+/**
+ * Error types for Toggly SDK
+ */
+declare class TogglyError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+declare class TogglyNetworkError extends TogglyError {
+    constructor(message: string, cause?: unknown);
+}
+declare class TogglyConfigError extends TogglyError {
+    constructor(message: string);
+}
+declare class TogglyTimeoutError extends TogglyError {
+    constructor(message: string);
+}
+
+/** Cookie/storage key names */
+declare const STORAGE_KEYS: {
+    /** Identity cookie/storage key */
+    readonly IDENTITY: "toggly_identity";
+    /** Feature flags cache key */
+    readonly FLAGS: "toggly_flags";
+    /** Config cache key */
+    readonly CONFIG: "toggly_config";
+    /** Last fetch timestamp key */
+    readonly LAST_FETCH: "toggly_last_fetch";
+};
+/** HTTP header names */
+declare const HEADERS: {
+    /** Identity header */
+    readonly IDENTITY: "x-toggly-identity";
+    /** Feature flags header */
+    readonly FLAGS: "x-toggly-flags";
+    /** Cache control */
+    readonly CACHE_CONTROL: "cache-control";
+};
+/** Meta key for loader data */
+declare const TOGGLY_LOADER_KEY: "__toggly";
+
+/**
+ * Toggly context value
+ */
+interface TogglyContextValue {
+    /** Current feature flags */
+    flags: FeatureFlags;
+    /** Whether the client is initialized */
+    isReady: boolean;
+    /** Current identity */
+    identity?: string;
+    /** Check if a feature is enabled */
+    isEnabled: (featureKey: string, defaultValue?: boolean, entity?: TogglyEntityContext | Record<string, unknown> | null, kind?: string) => boolean;
+    /** Check if a feature is disabled */
+    isDisabled: (featureKey: string, defaultValue?: boolean, entity?: TogglyEntityContext | Record<string, unknown> | null, kind?: string) => boolean;
+    /** Evaluate a feature gate */
+    evaluateGate: (featureKeys: string[], requirement?: 'all' | 'any', negate?: boolean, entity?: TogglyEntityContext | Record<string, unknown> | null, kind?: string) => boolean;
+    /** Register a domain-object mapper for entity-context evaluation */
+    registerContext: <T>(kind: string, mapper: (entity: T) => TogglyEntityContext) => void;
+    /** Set user identity */
+    identify: (identity: string, context?: IdentityContext) => Promise<void>;
+    /** Clear user identity */
+    reset: () => Promise<void>;
+    /** Refresh feature flags */
+    refresh: () => Promise<void>;
+    /** Add a hook */
+    addHook: (hook: TogglyHook) => void;
+    /** Remove a hook by name */
+    removeHook: (name: string) => boolean;
+    /** Register device-local post-filter gates */
+    setLocalGates: (gates: LocalGate[]) => void;
+    /** Notify subscribers that local gate state changed (no network) */
+    notifyLocalGatesChanged: () => void;
+    /** Subscribe to local gate changes */
+    subscribeLocalGatesChanged: (listener: () => void) => () => void;
+}
+/**
+ * Toggly provider props
+ */
+interface TogglyProviderProps {
+    /** Child components */
+    children: ReactNode;
+    /** Server-side feature context for hydration */
+    serverContext?: ServerFeatureContext;
+    /** Toggly configuration */
+    config?: TogglyConfig;
+    /** Enable client-side refresh */
+    enableRefresh?: boolean;
+    /** Refresh interval in milliseconds */
+    refreshInterval?: number;
+    /** Callback when flags are updated */
+    onFlagsChange?: (flags: FeatureFlags) => void;
+}
+declare const TogglyContext: react.Context<TogglyContextValue | undefined>;
+/**
+ * Toggly Provider component
+ */
+declare function TogglyProvider({ children, serverContext, config, enableRefresh, refreshInterval, onFlagsChange, }: TogglyProviderProps): ReactElement;
+/**
+ * Hook to access Toggly context
+ */
+declare function useTogglyContext(): TogglyContextValue;
+
+/**
+ * Hook to access the Toggly context
+ */
+declare function useToggly(): TogglyContextValue;
+/**
+ * Hook to check if a feature is enabled
+ */
+declare function useFeature(featureKey: string, defaultValue?: boolean, entity?: TogglyEntityContext | Record<string, unknown> | null, kind?: string): boolean;
+/**
+ * Hook to check if a feature is disabled
+ */
+declare function useFeatureDisabled(featureKey: string, defaultValue?: boolean, entity?: TogglyEntityContext | Record<string, unknown> | null, kind?: string): boolean;
+/**
+ * Hook to evaluate a feature gate (multiple features)
+ */
+declare function useFeatureGate(featureKeys: string[], requirement?: FeatureRequirement, negate?: boolean, entity?: TogglyEntityContext | Record<string, unknown> | null, kind?: string): boolean;
+/**
+ * Hook to get all feature flags
+ */
+declare function useFeatureFlags(): FeatureFlags;
+/**
+ * Hook to check multiple features at once
+ */
+declare function useFeatures(featureKeys: string[], defaultValue?: boolean): Record<string, boolean>;
+/**
+ * Hook for feature flag with callback
+ */
+declare function useFeatureCallback<T>(featureKey: string, enabledCallback: () => T, disabledCallback: () => T, defaultValue?: boolean): T;
+/**
+ * Hook to get feature value with typing
+ */
+declare function useFeatureValue<T>(featureKey: string, enabledValue: T, disabledValue: T, defaultValue?: boolean): T;
+/**
+ * Hook to track feature flag changes
+ */
+declare function useFeatureChange(featureKey: string, _onChange: (enabled: boolean) => void): boolean;
+/**
+ * Hook for identity management
+ */
+declare function useIdentity(): {
+    identity: string | undefined;
+    identify: (identity: string, context?: IdentityContext) => Promise<void>;
+    reset: () => Promise<void>;
+};
+/**
+ * Hook to check if Toggly is ready
+ */
+declare function useTogglyReady(): boolean;
+/**
+ * Hook for refreshing flags
+ */
+declare function useRefreshFlags(): () => Promise<void>;
+/**
+ * Hook for conditional rendering based on feature
+ */
+declare function useFeatureRender<T>(featureKey: string, enabled: T, disabled: T, defaultValue?: boolean): T;
+/**
+ * Hook for A/B testing with feature flags
+ */
+declare function useABTest(featureKey: string, variantA: string, variantB: string, defaultVariant?: 'A' | 'B'): string;
+/**
+ * Hook to get a feature with loading state
+ */
+declare function useFeatureWithLoading(featureKey: string, defaultValue?: boolean): {
+    enabled: boolean;
+    isLoading: boolean;
+};
+
+/**
+ * Feature component for declarative feature flag rendering
+ */
+
+/**
+ * Props for Feature component
+ */
+interface FeatureProps {
+    /** Feature key to check */
+    featureKey?: string;
+    /** Multiple feature keys to check */
+    featureKeys?: string[];
+    /** Requirement type when using multiple features */
+    requirement?: FeatureRequirement;
+    /** Negate the feature check — use for the off path (same as .NET `<feature negate>`) */
+    negate?: boolean;
+    /** Default value if feature is not found */
+    defaultValue?: boolean;
+    /** Content to render when the gate passes */
+    children?: ReactNode;
+    /** Render prop for custom rendering */
+    render?: (enabled: boolean) => ReactNode;
+    /** Entity context for mixed evaluated-signed gates */
+    context?: TogglyEntityContext | Record<string, unknown> | null;
+    /** Context kind for registerContext mapper lookup */
+    contextKind?: string;
+}
+/**
+ * Feature component for conditional rendering based on feature flags
+ *
+ * @example
+ * // Simple usage
+ * <Feature featureKey="new-dashboard">
+ *   <NewDashboard />
+ * </Feature>
+ *
+ * @example
+ * // Off path with negate
+ * <Feature featureKey="maintenance-mode" negate>
+ *   <MainContent />
+ * </Feature>
+ *
+ * @example
+ * // Multiple features (all required)
+ * <Feature featureKeys={["premium", "analytics"]} requirement="all">
+ *   <PremiumAnalytics />
+ * </Feature>
+ *
+ * @example
+ * // Render prop
+ * <Feature featureKey="dark-mode" render={(enabled) => (
+ *   <div className={enabled ? 'dark' : 'light'}>Content</div>
+ * )} />
+ */
+declare function Feature({ featureKey, featureKeys, requirement, negate, defaultValue, children, render, context, contextKind, }: FeatureProps): ReactElement | null;
+/**
+ * Props for FeatureEnabled component.
+ * Component is deprecated — prefer `<Feature featureKey="…">`.
+ */
+interface FeatureEnabledProps {
+    /** Feature key to check */
+    featureKey: string;
+    /** Default value if feature is not found */
+    defaultValue?: boolean;
+    /** Content to render when feature is enabled */
+    children: ReactNode;
+}
+/**
+ * Component that only renders children when feature is enabled
+ *
+ * @deprecated Use `<Feature featureKey="…">` instead
+ *
+ * @example
+ * <Feature featureKey="premium">
+ *   <PremiumContent />
+ * </Feature>
+ */
+declare function FeatureEnabled({ featureKey, defaultValue, children, }: Readonly<FeatureEnabledProps>): ReactElement | null;
+/**
+ * Props for FeatureDisabled component.
+ * Component is deprecated — prefer `<Feature featureKey="…" negate>`.
+ */
+interface FeatureDisabledProps {
+    /** Feature key to check */
+    featureKey: string;
+    /** Default value if feature is not found */
+    defaultValue?: boolean;
+    /** Content to render when feature is disabled */
+    children: ReactNode;
+}
+/**
+ * Component that only renders children when feature is disabled
+ *
+ * @deprecated Use `<Feature featureKey="…" negate>` instead
+ *
+ * @example
+ * <Feature featureKey="new-ui" negate>
+ *   <LegacyUI />
+ * </Feature>
+ */
+declare function FeatureDisabled({ featureKey, defaultValue, children, }: Readonly<FeatureDisabledProps>): ReactElement | null;
+/**
+ * Props for FeatureSwitch component
+ */
+interface FeatureSwitchProps {
+    /** Feature key to check */
+    featureKey: string;
+    /** Default value if feature is not found */
+    defaultValue?: boolean;
+    /** Content to render when feature is enabled */
+    enabled: ReactNode;
+    /** Content to render when feature is disabled */
+    disabled: ReactNode;
+}
+/**
+ * Component that renders different content based on feature state
+ *
+ * @example
+ * <FeatureSwitch
+ *   featureKey="new-pricing"
+ *   enabled={<NewPricing />}
+ *   disabled={<OldPricing />}
+ * />
+ */
+declare function FeatureSwitch({ featureKey, defaultValue, enabled, disabled, }: FeatureSwitchProps): ReactElement;
+/**
+ * Props for FeatureGate component
+ */
+interface FeatureGateProps {
+    /** Feature keys to check */
+    featureKeys: string[];
+    /** Requirement type */
+    requirement?: FeatureRequirement;
+    /** Negate the check */
+    negate?: boolean;
+    /** Content to render when gate passes */
+    children: ReactNode;
+    /** Entity context for mixed evaluated-signed gates */
+    context?: TogglyEntityContext | Record<string, unknown> | null;
+    /** Context kind for registerContext mapper lookup */
+    contextKind?: string;
+}
+/**
+ * Component for checking multiple features
+ *
+ * @example
+ * <FeatureGate featureKeys={["premium", "beta"]} requirement="all">
+ *   <BetaFeature />
+ * </FeatureGate>
+ */
+declare function FeatureGate({ featureKeys, requirement, negate, children, context, contextKind, }: FeatureGateProps): ReactElement | null;
+
+/**
+ * React Router-specific utilities for Toggly
+ */
+type SerializeFrom<T> = T;
+
+/**
+ * Props for RouterTogglyProvider
+ */
+interface RouterTogglyProviderProps extends Omit<TogglyProviderProps, 'serverContext'> {
+    /** Route ID to get loader data from (optional) */
+    routeId?: string;
+    /** Fallback server context if not in loader data */
+    fallbackContext?: ServerFeatureContext;
+}
+/**
+ * React Router-specific Toggly Provider that automatically hydrates from loader data
+ *
+ * @example
+ * // In root.tsx
+ * export default function App() {
+ *   return (
+ *     <RouterTogglyProvider>
+ *       <Outlet />
+ *     </RouterTogglyProvider>
+ *   );
+ * }
+ */
+declare function RouterTogglyProvider({ children, routeId, fallbackContext, config, ...props }: RouterTogglyProviderProps): ReactElement;
+/**
+ * Hook to get Toggly context from loader data
+ */
+declare function useTogglyLoaderData<T extends Record<string, unknown> = Record<string, unknown>>(): {
+    data: SerializeFrom<T>;
+    toggly: ServerFeatureContext | undefined;
+};
+/**
+ * Hook to get Toggly context from a specific route's loader data
+ */
+declare function useTogglyRouteLoaderData<T extends Record<string, unknown> = Record<string, unknown>>(routeId: string): {
+    data: SerializeFrom<T> | undefined;
+    toggly: ServerFeatureContext | undefined;
+};
+/**
+ * Helper to extract server context from loader data
+ */
+declare function extractServerContext<T extends Record<string, unknown>>(loaderData: T & {
+    [TOGGLY_LOADER_KEY]?: ServerFeatureContext;
+}): ServerFeatureContext | undefined;
+/**
+ * Helper to check if loader data has Toggly context
+ */
+declare function hasTogglyContext<T extends Record<string, unknown>>(loaderData: T): loaderData is T & {
+    [TOGGLY_LOADER_KEY]: ServerFeatureContext;
+};
+/**
+ * Type helper for loader data with Toggly context
+ */
+type LoaderDataWithToggly<T extends Record<string, unknown>> = T & {
+    [TOGGLY_LOADER_KEY]: ServerFeatureContext;
+};
+/**
+ * Script component to inject Toggly flags for client-side hydration
+ *
+ * @example
+ * // In root.tsx head
+ * <TogglyScript serverContext={togglyContext} />
+ */
+declare function TogglyScript({ serverContext, nonce, }: {
+    serverContext?: ServerFeatureContext;
+    nonce?: string;
+}): ReactElement | null;
+/**
+ * Get server context from window for client-side hydration
+ */
+declare function getWindowTogglyData(): ServerFeatureContext | undefined;
+
+export { type EvaluationResult, type EvaluationSeriesData, Feature, FeatureDisabled, type FeatureDisabledProps, FeatureEnabled, type FeatureEnabledProps, type FeatureFlags, FeatureGate, type FeatureGateProps, type FeatureProps, type FeatureRequirement, FeatureSwitch, type FeatureSwitchProps, HEADERS, type HookMetadata, type IdentityContext, type IdentitySeriesData, type LoaderDataWithToggly, RouterTogglyProvider, type RouterTogglyProviderProps, STORAGE_KEYS, type ServerFeatureContext, TOGGLY_LOADER_KEY, type TogglyConfig, TogglyConfigError, TogglyContext, type TogglyContextValue, TogglyError, type TogglyHook, TogglyNetworkError, TogglyProvider, type TogglyProviderProps, TogglyScript, TogglyTimeoutError, extractServerContext, getWindowTogglyData, hasTogglyContext, useABTest, useFeature, useFeatureCallback, useFeatureChange, useFeatureDisabled, useFeatureFlags, useFeatureGate, useFeatureRender, useFeatureValue, useFeatureWithLoading, useFeatures, useIdentity, useRefreshFlags, useToggly, useTogglyContext, useTogglyLoaderData, useTogglyReady, useTogglyRouteLoaderData };