@supashiphq/javascript-sdk 0.7.7

package/dist/index.d.mts

@@ -0,0 +1,261 @@
+interface SupaPluginConfig {
+    enabled?: boolean;
+}
+interface Plugin {
+    name: string;
+}
+interface SupaPlugin extends Plugin {
+    onInit?(params: {
+        clientId: string;
+        availableFeatures: Record<string, FeatureValue>;
+        context?: FeatureContext;
+    }): Promise<void> | void;
+    beforeGetFeatures?(featureNames: string[], context?: FeatureContext): Promise<void>;
+    afterGetFeatures?(results: Record<string, FeatureValue>, context?: FeatureContext): Promise<void>;
+    onError?(error: Error, context?: FeatureContext): Promise<void>;
+    beforeRequest?(url: string, body: unknown, headers: Record<string, string>): Promise<void>;
+    afterResponse?(response: Response, timing: {
+        duration: number;
+    }): Promise<void>;
+    onContextUpdate?(oldContext: FeatureContext | undefined, newContext: FeatureContext, source: 'updateContext' | 'request'): Promise<void>;
+    onRetryAttempt?(attempt: number, error: Error, willRetry: boolean): Promise<void>;
+    onFallbackUsed?(featureName: string, fallbackValue: FeatureValue, reason: Error): Promise<void>;
+}
+
+interface SupaToolbarPosition {
+    placement?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+    offset?: {
+        x: string;
+        y: string;
+    };
+}
+type SupaToolbarOverrideChange = {
+    feature: string;
+    value: FeatureValue;
+};
+type SupaToolbarOverrideChangeCallback = (featureOverride: SupaToolbarOverrideChange, allOverrides: Record<string, FeatureValue>) => void;
+interface SupaToolbarPluginConfig extends Omit<SupaPluginConfig, 'enabled'> {
+    enabled?: boolean | 'auto';
+    position?: SupaToolbarPosition;
+    onOverrideChange?: SupaToolbarOverrideChangeCallback;
+}
+/**
+ * Toolbar plugin for local feature flag testing
+ * Provides a visual interface to override feature flags during development
+ */
+declare class SupaToolbarPlugin implements SupaPlugin {
+    name: string;
+    private config;
+    private state;
+    private clientId?;
+    private storageKey;
+    constructor(config?: SupaToolbarPluginConfig);
+    cleanup(): void;
+    private shouldShowToolbar;
+    onInit(params: {
+        availableFeatures: Record<string, FeatureValue>;
+        context?: FeatureContext;
+        clientId: string;
+    }): void;
+    beforeGetFeatures(_featureNames: string[], context?: FeatureContext): Promise<void>;
+    afterGetFeatures(results: Record<string, FeatureValue>, context?: FeatureContext): Promise<void>;
+    private loadOverrides;
+    private saveOverrides;
+    setOverride(featureName: string, value: FeatureValue): void;
+    removeOverride(featureName: string): void;
+    clearAllOverrides(): void;
+    getOverrides(): Record<string, FeatureValue>;
+    private injectToolbar;
+    private removeToolbar;
+    private getToolbarHTML;
+    private injectStyles;
+    private attachEventListeners;
+    private updateToolbarUI;
+    private escapeHtml;
+}
+
+interface SupaClientConfig {
+    /**
+     * API key used to authenticate requests to Supaship services.
+     * Typically created in your project settings.
+     */
+    apiKey: string;
+    /**
+     * Environment identifier used for feature flag evaluation (e.g. "production", "staging").
+     */
+    environment: string;
+    /**
+     * Feature definitions with their fallback values.
+     * Use `satisfies FeaturesWithFallbacks` for type safety.
+     * Defines all feature flags used in the application.
+     */
+    features: FeaturesWithFallbacks;
+    /**
+     * Default context included with every feature evaluation request.
+     * Can be merged/overridden per-call via options.context.
+     */
+    context: FeatureContext;
+    /**
+     * Optional network configuration allowing you to override API endpoints.
+     * If omitted, defaults are used.
+     */
+    networkConfig?: NetworkConfig;
+    /**
+     * Optional plugins to observe or augment client behavior.
+     */
+    plugins?: SupaPlugin[];
+    /**
+     * Toolbar plugin configuration (browser only).
+     * - `false`: Disable toolbar (opt-out)
+     * - `undefined`: Enable with defaults (enabled: 'auto')
+     * - `object`: Custom configuration
+     *
+     * Default: Enabled in browser with 'auto' mode (shows only on localhost)
+     */
+    toolbar?: false | SupaToolbarPluginConfig;
+}
+interface FeatureContext {
+    [key: string]: string | number | boolean | null | undefined;
+}
+interface NetworkConfig {
+    /**
+     * Fully-qualified URL to the features evaluation endpoint.
+     * Example: "https://edge.supaship.com/v1/features"
+     */
+    featuresAPIUrl?: string;
+    /**
+     * Fully-qualified URL to the events/analytics endpoint.
+     * Example: "https://edge.supaship.com/v1/events"
+     */
+    eventsAPIUrl?: string;
+    /**
+     * Retry behavior for network requests (exponential backoff).
+     */
+    retry?: RetryConfig;
+    /**
+     * Request timeout in milliseconds. If provided, requests will be aborted after this duration.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Optional fetch implementation to use (e.g., node-fetch for Node < 18).
+     */
+    fetchFn?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+interface RetryConfig {
+    enabled?: boolean;
+    maxAttempts?: number;
+    backoff?: number;
+}
+/**
+ * Supported feature flag value types.
+ * - boolean: true/false flags
+ * - object: structured configuration data
+ * - array: lists of items
+ * - null: disabled/empty state
+ */
+type FeatureValue = boolean | null | Record<string, unknown> | unknown[];
+/**
+ * Widens boolean literals to boolean type while preserving other types.
+ * This allows `false` and `true` to be inferred as `boolean` for better ergonomics.
+ * @internal
+ */
+type WidenFeatureValue<T> = T extends boolean ? boolean : T extends readonly unknown[] ? T extends readonly (infer U)[] ? U[] : T : T;
+/**
+ * Widens all feature values in a features object.
+ * @internal
+ */
+type WidenFeatures<T extends Record<string, FeatureValue>> = {
+    [K in keyof T]: WidenFeatureValue<T[K]>;
+};
+/**
+ * ⚠️ IMPORTANT: Use with `satisfies` operator, NOT type annotation
+ *
+ * Type representing feature flag definitions with their fallback values.
+ * Used to configure the SupaClient with feature flags.
+ *
+ * **Why `satisfies` over type annotation:**
+ * - ✅ `satisfies` preserves exact types ('feature-flag' stays 'feature-flag')
+ * - ❌ Type annotation widens types ('feature-flag' becomes string)
+ *
+ * Supported feature value types:
+ * - boolean: simple on/off flags
+ * - object: structured configuration data
+ * - array: lists of values
+ * - null: disabled state
+ *
+ * @example
+ * ```ts
+ * import { FeaturesWithFallbacks } from '@supashiphq/javascript-sdk'
+ *
+ * // ✅ RECOMMENDED: satisfies ✅
+ * const features = {
+ *   'dark-mode': false,
+ *   'ui-config': {
+ *     theme: 'light' as const,
+ *     showWelcome: true,
+ *   },
+ * } satisfies FeaturesWithFallbacks
+ *
+ * // ❌ AVOID: Type annotation ❌
+ * const features: FeaturesWithFallbacks = {
+ *   'dark-mode': false,
+ *   'ui-config': {
+ *     theme: 'light',
+ *     showWelcome: true,
+ *   },
+ * }
+ * ```
+ */
+type FeaturesWithFallbacks = Record<string, FeatureValue>;
+/**
+ * Type alias for widened feature definitions.
+ * This is the type that gets stored and used internally.
+ */
+type Features<T extends FeaturesWithFallbacks> = WidenFeatures<T>;
+
+declare class SupaClient<TFeatures extends FeaturesWithFallbacks> {
+    private apiKey;
+    private environment;
+    private defaultContext?;
+    private plugins;
+    private featureDefinitions;
+    private clientId;
+    private fetchImpl;
+    private networkConfig;
+    constructor(config: SupaClientConfig & {
+        features: TFeatures;
+    });
+    /**
+     * Generate a unique client ID
+     */
+    private generateClientId;
+    /**
+     * Initialize plugins with automatic toolbar plugin in browser environments
+     */
+    private initializePlugins;
+    /**
+     * Updates the default context for the client
+     * @param context - New context to merge with or replace the existing context
+     * @param mergeWithExisting - Whether to merge with existing context (default: true)
+     */
+    updateContext(context: FeatureContext, mergeWithExisting?: boolean): void;
+    /**
+     * Gets the current default context
+     */
+    getContext(): FeatureContext | undefined;
+    /**
+     * Gets the fallback value for a feature from its definition
+     */
+    getFeatureFallback<TKey extends keyof TFeatures>(featureName: TKey): Features<TFeatures>[TKey];
+    private getVariationValue;
+    getFeature<TKey extends keyof TFeatures>(featureName: TKey, options?: {
+        context?: FeatureContext;
+    }): Promise<Features<TFeatures>[TKey]>;
+    getFeatures<TKeys extends readonly (keyof TFeatures)[]>(featureNames: TKeys, options?: {
+        context?: FeatureContext;
+    }): Promise<{
+        [K in TKeys[number]]: Features<TFeatures>[K];
+    }>;
+}
+
+export { type FeatureContext, type FeatureValue, type Features, type FeaturesWithFallbacks, type NetworkConfig, type RetryConfig, SupaClient, type SupaClientConfig, type SupaPlugin, type SupaPluginConfig, type SupaToolbarOverrideChange, type SupaToolbarOverrideChangeCallback, type SupaToolbarPluginConfig, type SupaToolbarPosition, SupaToolbarPlugin as ToolbarPlugin, type WidenFeatureValue, type WidenFeatures };

package/dist/index.d.ts

@@ -0,0 +1,261 @@
+interface SupaPluginConfig {
+    enabled?: boolean;
+}
+interface Plugin {
+    name: string;
+}
+interface SupaPlugin extends Plugin {
+    onInit?(params: {
+        clientId: string;
+        availableFeatures: Record<string, FeatureValue>;
+        context?: FeatureContext;
+    }): Promise<void> | void;
+    beforeGetFeatures?(featureNames: string[], context?: FeatureContext): Promise<void>;
+    afterGetFeatures?(results: Record<string, FeatureValue>, context?: FeatureContext): Promise<void>;
+    onError?(error: Error, context?: FeatureContext): Promise<void>;
+    beforeRequest?(url: string, body: unknown, headers: Record<string, string>): Promise<void>;
+    afterResponse?(response: Response, timing: {
+        duration: number;
+    }): Promise<void>;
+    onContextUpdate?(oldContext: FeatureContext | undefined, newContext: FeatureContext, source: 'updateContext' | 'request'): Promise<void>;
+    onRetryAttempt?(attempt: number, error: Error, willRetry: boolean): Promise<void>;
+    onFallbackUsed?(featureName: string, fallbackValue: FeatureValue, reason: Error): Promise<void>;
+}
+
+interface SupaToolbarPosition {
+    placement?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+    offset?: {
+        x: string;
+        y: string;
+    };
+}
+type SupaToolbarOverrideChange = {
+    feature: string;
+    value: FeatureValue;
+};
+type SupaToolbarOverrideChangeCallback = (featureOverride: SupaToolbarOverrideChange, allOverrides: Record<string, FeatureValue>) => void;
+interface SupaToolbarPluginConfig extends Omit<SupaPluginConfig, 'enabled'> {
+    enabled?: boolean | 'auto';
+    position?: SupaToolbarPosition;
+    onOverrideChange?: SupaToolbarOverrideChangeCallback;
+}
+/**
+ * Toolbar plugin for local feature flag testing
+ * Provides a visual interface to override feature flags during development
+ */
+declare class SupaToolbarPlugin implements SupaPlugin {
+    name: string;
+    private config;
+    private state;
+    private clientId?;
+    private storageKey;
+    constructor(config?: SupaToolbarPluginConfig);
+    cleanup(): void;
+    private shouldShowToolbar;
+    onInit(params: {
+        availableFeatures: Record<string, FeatureValue>;
+        context?: FeatureContext;
+        clientId: string;
+    }): void;
+    beforeGetFeatures(_featureNames: string[], context?: FeatureContext): Promise<void>;
+    afterGetFeatures(results: Record<string, FeatureValue>, context?: FeatureContext): Promise<void>;
+    private loadOverrides;
+    private saveOverrides;
+    setOverride(featureName: string, value: FeatureValue): void;
+    removeOverride(featureName: string): void;
+    clearAllOverrides(): void;
+    getOverrides(): Record<string, FeatureValue>;
+    private injectToolbar;
+    private removeToolbar;
+    private getToolbarHTML;
+    private injectStyles;
+    private attachEventListeners;
+    private updateToolbarUI;
+    private escapeHtml;
+}
+
+interface SupaClientConfig {
+    /**
+     * API key used to authenticate requests to Supaship services.
+     * Typically created in your project settings.
+     */
+    apiKey: string;
+    /**
+     * Environment identifier used for feature flag evaluation (e.g. "production", "staging").
+     */
+    environment: string;
+    /**
+     * Feature definitions with their fallback values.
+     * Use `satisfies FeaturesWithFallbacks` for type safety.
+     * Defines all feature flags used in the application.
+     */
+    features: FeaturesWithFallbacks;
+    /**
+     * Default context included with every feature evaluation request.
+     * Can be merged/overridden per-call via options.context.
+     */
+    context: FeatureContext;
+    /**
+     * Optional network configuration allowing you to override API endpoints.
+     * If omitted, defaults are used.
+     */
+    networkConfig?: NetworkConfig;
+    /**
+     * Optional plugins to observe or augment client behavior.
+     */
+    plugins?: SupaPlugin[];
+    /**
+     * Toolbar plugin configuration (browser only).
+     * - `false`: Disable toolbar (opt-out)
+     * - `undefined`: Enable with defaults (enabled: 'auto')
+     * - `object`: Custom configuration
+     *
+     * Default: Enabled in browser with 'auto' mode (shows only on localhost)
+     */
+    toolbar?: false | SupaToolbarPluginConfig;
+}
+interface FeatureContext {
+    [key: string]: string | number | boolean | null | undefined;
+}
+interface NetworkConfig {
+    /**
+     * Fully-qualified URL to the features evaluation endpoint.
+     * Example: "https://edge.supaship.com/v1/features"
+     */
+    featuresAPIUrl?: string;
+    /**
+     * Fully-qualified URL to the events/analytics endpoint.
+     * Example: "https://edge.supaship.com/v1/events"
+     */
+    eventsAPIUrl?: string;
+    /**
+     * Retry behavior for network requests (exponential backoff).
+     */
+    retry?: RetryConfig;
+    /**
+     * Request timeout in milliseconds. If provided, requests will be aborted after this duration.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Optional fetch implementation to use (e.g., node-fetch for Node < 18).
+     */
+    fetchFn?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+interface RetryConfig {
+    enabled?: boolean;
+    maxAttempts?: number;
+    backoff?: number;
+}
+/**
+ * Supported feature flag value types.
+ * - boolean: true/false flags
+ * - object: structured configuration data
+ * - array: lists of items
+ * - null: disabled/empty state
+ */
+type FeatureValue = boolean | null | Record<string, unknown> | unknown[];
+/**
+ * Widens boolean literals to boolean type while preserving other types.
+ * This allows `false` and `true` to be inferred as `boolean` for better ergonomics.
+ * @internal
+ */
+type WidenFeatureValue<T> = T extends boolean ? boolean : T extends readonly unknown[] ? T extends readonly (infer U)[] ? U[] : T : T;
+/**
+ * Widens all feature values in a features object.
+ * @internal
+ */
+type WidenFeatures<T extends Record<string, FeatureValue>> = {
+    [K in keyof T]: WidenFeatureValue<T[K]>;
+};
+/**
+ * ⚠️ IMPORTANT: Use with `satisfies` operator, NOT type annotation
+ *
+ * Type representing feature flag definitions with their fallback values.
+ * Used to configure the SupaClient with feature flags.
+ *
+ * **Why `satisfies` over type annotation:**
+ * - ✅ `satisfies` preserves exact types ('feature-flag' stays 'feature-flag')
+ * - ❌ Type annotation widens types ('feature-flag' becomes string)
+ *
+ * Supported feature value types:
+ * - boolean: simple on/off flags
+ * - object: structured configuration data
+ * - array: lists of values
+ * - null: disabled state
+ *
+ * @example
+ * ```ts
+ * import { FeaturesWithFallbacks } from '@supashiphq/javascript-sdk'
+ *
+ * // ✅ RECOMMENDED: satisfies ✅
+ * const features = {
+ *   'dark-mode': false,
+ *   'ui-config': {
+ *     theme: 'light' as const,
+ *     showWelcome: true,
+ *   },
+ * } satisfies FeaturesWithFallbacks
+ *
+ * // ❌ AVOID: Type annotation ❌
+ * const features: FeaturesWithFallbacks = {
+ *   'dark-mode': false,
+ *   'ui-config': {
+ *     theme: 'light',
+ *     showWelcome: true,
+ *   },
+ * }
+ * ```
+ */
+type FeaturesWithFallbacks = Record<string, FeatureValue>;
+/**
+ * Type alias for widened feature definitions.
+ * This is the type that gets stored and used internally.
+ */
+type Features<T extends FeaturesWithFallbacks> = WidenFeatures<T>;
+
+declare class SupaClient<TFeatures extends FeaturesWithFallbacks> {
+    private apiKey;
+    private environment;
+    private defaultContext?;
+    private plugins;
+    private featureDefinitions;
+    private clientId;
+    private fetchImpl;
+    private networkConfig;
+    constructor(config: SupaClientConfig & {
+        features: TFeatures;
+    });
+    /**
+     * Generate a unique client ID
+     */
+    private generateClientId;
+    /**
+     * Initialize plugins with automatic toolbar plugin in browser environments
+     */
+    private initializePlugins;
+    /**
+     * Updates the default context for the client
+     * @param context - New context to merge with or replace the existing context
+     * @param mergeWithExisting - Whether to merge with existing context (default: true)
+     */
+    updateContext(context: FeatureContext, mergeWithExisting?: boolean): void;
+    /**
+     * Gets the current default context
+     */
+    getContext(): FeatureContext | undefined;
+    /**
+     * Gets the fallback value for a feature from its definition
+     */
+    getFeatureFallback<TKey extends keyof TFeatures>(featureName: TKey): Features<TFeatures>[TKey];
+    private getVariationValue;
+    getFeature<TKey extends keyof TFeatures>(featureName: TKey, options?: {
+        context?: FeatureContext;
+    }): Promise<Features<TFeatures>[TKey]>;
+    getFeatures<TKeys extends readonly (keyof TFeatures)[]>(featureNames: TKeys, options?: {
+        context?: FeatureContext;
+    }): Promise<{
+        [K in TKeys[number]]: Features<TFeatures>[K];
+    }>;
+}
+
+export { type FeatureContext, type FeatureValue, type Features, type FeaturesWithFallbacks, type NetworkConfig, type RetryConfig, SupaClient, type SupaClientConfig, type SupaPlugin, type SupaPluginConfig, type SupaToolbarOverrideChange, type SupaToolbarOverrideChangeCallback, type SupaToolbarPluginConfig, type SupaToolbarPosition, SupaToolbarPlugin as ToolbarPlugin, type WidenFeatureValue, type WidenFeatures };