@supashiphq/react-sdk 0.7.7

package/dist/index.d.mts

@@ -0,0 +1,260 @@
+import { FeaturesWithFallbacks, FeatureValue, FeatureContext, Features as Features$1, SupaClientConfig, SupaToolbarPluginConfig, SupaClient } from '@supashiphq/javascript-sdk';
+export { FeatureContext, FeatureValue, FeaturesWithFallbacks, SupaPlugin, SupaClientConfig as SupaProviderConfig, SupaToolbarPluginConfig, SupaToolbarPosition } from '@supashiphq/javascript-sdk';
+import React, { ReactNode } from 'react';
+
+type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
+interface BaseQueryState<TData = unknown, TError = Error> {
+    status: QueryStatus;
+    data: TData | undefined;
+    error: TError | null;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    isIdle: boolean;
+    isFetching: boolean;
+    dataUpdatedAt: number;
+}
+interface QueryState<TData = unknown, TError = Error> extends BaseQueryState<TData, TError> {
+    refetch: () => Promise<void>;
+}
+declare function getInitialQueryState<TData, TError>(initialData?: TData, enabled?: boolean): BaseQueryState<TData, TError>;
+interface UseQueryOptions<TData = unknown, TError = Error> {
+    enabled?: boolean;
+    retry?: number | boolean;
+    retryDelay?: number;
+    staleTime?: number;
+    cacheTime?: number;
+    refetchOnWindowFocus?: boolean;
+    initialData?: TData;
+    onSuccess?: (data: TData) => void;
+    onError?: (error: TError) => void;
+    onSettled?: (data: TData | undefined, error: TError | null) => void;
+}
+type QueryKey = unknown[];
+declare class QueryCache {
+    private cache;
+    private timers;
+    private observers;
+    getQuery(queryKey: string): unknown;
+    isStale(queryKey: string, staleTime: number): boolean;
+    setQuery(queryKey: string, data: unknown, cacheTime?: number): void;
+    subscribe(queryKey: string, callback: () => void): () => void;
+    private notifyObservers;
+    invalidateQuery(queryKey: string): void;
+    invalidateQueries(queryKeyPrefix: string): void;
+    clear(): void;
+}
+declare const queryCache: QueryCache;
+declare class QueryClient {
+    private cache;
+    constructor(cache?: QueryCache);
+    /**
+     * Invalidates a specific query by its query key
+     * This will remove it from cache and trigger refetch in all components using this query
+     */
+    invalidateQueries(queryKey: QueryKey): void;
+    /**
+     * Invalidates all queries matching a partial query key
+     * For example, invalidateQueriesByPrefix(['feature']) will invalidate all feature queries
+     */
+    invalidateQueriesByPrefix(queryKeyPrefix: QueryKey): void;
+    /**
+     * Clears all queries from the cache
+     */
+    clear(): void;
+}
+declare function useQueryClient(): QueryClient;
+declare function useQuery<TData = unknown, TError = Error>(queryKey: QueryKey, queryFn: () => Promise<TData>, options?: UseQueryOptions<TData, TError>): QueryState<TData, TError>;
+
+/**
+ * Helper type to infer feature types from your feature config for module augmentation.
+ *
+ * ⚠️ Remember: Define features with `satisfies FeaturesWithFallbacks`, not type annotation
+ *
+ * @example
+ * ```ts
+ * import { FeaturesWithFallbacks, InferFeatures } from '@supashiphq/react-sdk'
+ *
+ * // ✅ Use satisfies to preserve literal types
+ * export const FEATURE_FLAGS = {
+ *   'dark-mode': false,
+ *   'ui-config': { variant: 'a' as const }
+ * } satisfies FeaturesWithFallbacks
+ *
+ * declare module '@supashiphq/react-sdk' {
+ *   interface Features extends InferFeatures<typeof FEATURE_FLAGS> {}
+ * }
+ * ```
+ */
+type InferFeatures<T extends FeaturesWithFallbacks> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * Interface to be augmented by users for type-safe feature flags.
+ * Use InferFeatures helper to enable type-safe feature access.
+ *
+ * @example
+ * ```ts
+ * // lib/features.ts
+ * import { FeaturesWithFallbacks, InferFeatures } from '@supashiphq/react-sdk'
+ *
+ * export const FEATURE_FLAGS = {
+ *   'dark-mode': false,
+ *   'ui-config': {
+ *     variant: 'a' as const,
+ *     showWelcome: true,
+ *   },
+ * } satisfies FeaturesWithFallbacks
+ *
+ * declare module '@supashiphq/react-sdk' {
+ *   interface Features extends InferFeatures<typeof FEATURE_FLAGS> {}
+ * }
+ * ```
+ */
+interface Features {
+}
+/**
+ * Return type for useFeature hook with proper typing based on feature key
+ */
+type TypedFeatures = keyof Features extends never ? {
+    [key: string]: Omit<QueryState<FeatureValue | null>, 'data'> & {
+        feature: FeatureValue | null;
+    };
+} : {
+    [K in keyof Features]: Omit<QueryState<Features[K]>, 'data'> & {
+        feature: Features[K];
+    };
+};
+type FeatureKey = keyof Features extends never ? string : keyof Features;
+interface UseFeatureOptions {
+    context?: FeatureContext;
+    shouldFetch?: boolean;
+}
+interface UseFeaturesOptions {
+    context?: FeatureContext;
+    shouldFetch?: boolean;
+}
+
+interface UseFeatureResult<T extends FeatureValue> extends Omit<QueryState<T | null>, 'data'> {
+    feature: T | null;
+}
+interface UseFeaturesResult<T extends Record<string, FeatureValue>> extends Omit<QueryState<T>, 'data'> {
+    features: T;
+}
+/**
+ * Returns the state of a given feature for the current context.
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   const { feature, isLoading } = useFeature('my-feature')
+ *   if (isLoading) return <div>Loading...</div>
+ *   return <div>Feature value: {String(feature)}</div>
+ * }
+ * ```
+ *
+ * @remarks
+ * For type-safe feature flags, augment the Features interface:
+ * ```ts
+ * declare module '@supashiphq/react-sdk' {
+ *   interface Features {
+ *     'my-feature': { value: 'variant-a' | 'variant-b' }
+ *     'dark-mode': { value: boolean }
+ *   }
+ * }
+ *
+ * // Now get full type safety:
+ * const { feature } = useFeature('my-feature')
+ * // feature is typed as 'variant-a' | 'variant-b'
+ * ```
+ */
+declare function useFeature<TKey extends FeatureKey>(key: TKey, options?: {
+    context?: FeatureContext;
+    shouldFetch?: boolean;
+}): TypedFeatures[TKey];
+/**
+ * Extract feature value type from Features interface
+ */
+type ExtractFeatureValue<T> = T extends {
+    value: infer V;
+} ? V : FeatureValue;
+/**
+ * Returns the state of multiple features for the current context.
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   const { features, isLoading } = useFeatures(['feature-a', 'feature-b'])
+ *   if (isLoading) return <div>Loading...</div>
+ *   return <div>Feature A: {String(features['feature-a'])}</div>
+ * }
+ * ```
+ */
+declare function useFeatures<TKeys extends readonly FeatureKey[]>(featureNames: TKeys, options?: {
+    context?: FeatureContext;
+    shouldFetch?: boolean;
+}): UseFeaturesResult<{
+    [K in TKeys[number]]: K extends keyof Features ? ExtractFeatureValue<Features[K]> : FeatureValue | null;
+}>;
+
+interface SupaContextValue<TFeatures extends Features$1<Record<string, FeatureValue>>> {
+    client: SupaClient<TFeatures>;
+    updateContext: (context: FeatureContext, mergeWithExisting?: boolean) => void;
+    getContext: () => FeatureContext | undefined;
+}
+interface SupaProviderProps<TFeatures extends Features$1<Record<string, FeatureValue>>> {
+    config: Omit<SupaClientConfig, 'plugins' | 'toolbar'> & {
+        features: TFeatures;
+    };
+    toolbar?: SupaToolbarPluginConfig | boolean;
+    children: ReactNode;
+}
+declare function SupaProvider<TFeatures extends Features$1<Record<string, FeatureValue>>>({ config, toolbar, children, }: SupaProviderProps<TFeatures>): React.JSX.Element;
+declare function useClient<TFeatures extends Features$1<Record<string, FeatureValue>>>(): SupaClient<TFeatures>;
+/**
+ * Hook to update the context dynamically
+ * Useful when context depends on authentication or other async operations
+ */
+declare function useFeatureContext(): Omit<SupaContextValue<any>, 'client'>;
+
+interface SupaFeatureProps {
+    /**
+     * The feature flag key to evaluate
+     */
+    feature: FeatureKey;
+    /**
+     * Context for feature evaluation
+     */
+    context?: FeatureContext;
+    /**
+     * Whether to fetch the feature (default: true)
+     */
+    shouldFetch?: boolean;
+    /**
+     * Variations object mapping feature values/keys to JSX elements
+     */
+    variations: Record<string, ReactNode>;
+    /**
+     * Key in variations object to use for loading state
+     */
+    loading?: string;
+}
+/**
+ * SupaFeature component that conditionally renders variations based on feature flag values.
+ * Uses the default value defined in the client configuration.
+ *
+ * @example
+ * ```tsx
+ * <SupaFeature
+ *   feature="new-header"
+ *   variations={{
+ *     "true": <NewHeader />,
+ *     "false": <OldHeader />,
+ *     loading: <HeaderSkeleton />
+ *   }}
+ * />
+ * ```
+ */
+declare function SupaFeature({ feature, context, shouldFetch, variations, loading, }: SupaFeatureProps): React.JSX.Element | null;
+
+export { type BaseQueryState, type FeatureKey, type Features, type InferFeatures, QueryClient, type QueryKey, type QueryState, type QueryStatus, SupaFeature, type SupaFeatureProps, SupaProvider, type TypedFeatures, type UseFeatureOptions, type UseFeatureResult, type UseFeaturesOptions, type UseFeaturesResult, type UseQueryOptions, getInitialQueryState, queryCache, useClient, useFeature, useFeatureContext, useFeatures, useQuery, useQueryClient };

package/dist/index.d.ts

@@ -0,0 +1,260 @@
+import { FeaturesWithFallbacks, FeatureValue, FeatureContext, Features as Features$1, SupaClientConfig, SupaToolbarPluginConfig, SupaClient } from '@supashiphq/javascript-sdk';
+export { FeatureContext, FeatureValue, FeaturesWithFallbacks, SupaPlugin, SupaClientConfig as SupaProviderConfig, SupaToolbarPluginConfig, SupaToolbarPosition } from '@supashiphq/javascript-sdk';
+import React, { ReactNode } from 'react';
+
+type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
+interface BaseQueryState<TData = unknown, TError = Error> {
+    status: QueryStatus;
+    data: TData | undefined;
+    error: TError | null;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    isIdle: boolean;
+    isFetching: boolean;
+    dataUpdatedAt: number;
+}
+interface QueryState<TData = unknown, TError = Error> extends BaseQueryState<TData, TError> {
+    refetch: () => Promise<void>;
+}
+declare function getInitialQueryState<TData, TError>(initialData?: TData, enabled?: boolean): BaseQueryState<TData, TError>;
+interface UseQueryOptions<TData = unknown, TError = Error> {
+    enabled?: boolean;
+    retry?: number | boolean;
+    retryDelay?: number;
+    staleTime?: number;
+    cacheTime?: number;
+    refetchOnWindowFocus?: boolean;
+    initialData?: TData;
+    onSuccess?: (data: TData) => void;
+    onError?: (error: TError) => void;
+    onSettled?: (data: TData | undefined, error: TError | null) => void;
+}
+type QueryKey = unknown[];
+declare class QueryCache {
+    private cache;
+    private timers;
+    private observers;
+    getQuery(queryKey: string): unknown;
+    isStale(queryKey: string, staleTime: number): boolean;
+    setQuery(queryKey: string, data: unknown, cacheTime?: number): void;
+    subscribe(queryKey: string, callback: () => void): () => void;
+    private notifyObservers;
+    invalidateQuery(queryKey: string): void;
+    invalidateQueries(queryKeyPrefix: string): void;
+    clear(): void;
+}
+declare const queryCache: QueryCache;
+declare class QueryClient {
+    private cache;
+    constructor(cache?: QueryCache);
+    /**
+     * Invalidates a specific query by its query key
+     * This will remove it from cache and trigger refetch in all components using this query
+     */
+    invalidateQueries(queryKey: QueryKey): void;
+    /**
+     * Invalidates all queries matching a partial query key
+     * For example, invalidateQueriesByPrefix(['feature']) will invalidate all feature queries
+     */
+    invalidateQueriesByPrefix(queryKeyPrefix: QueryKey): void;
+    /**
+     * Clears all queries from the cache
+     */
+    clear(): void;
+}
+declare function useQueryClient(): QueryClient;
+declare function useQuery<TData = unknown, TError = Error>(queryKey: QueryKey, queryFn: () => Promise<TData>, options?: UseQueryOptions<TData, TError>): QueryState<TData, TError>;
+
+/**
+ * Helper type to infer feature types from your feature config for module augmentation.
+ *
+ * ⚠️ Remember: Define features with `satisfies FeaturesWithFallbacks`, not type annotation
+ *
+ * @example
+ * ```ts
+ * import { FeaturesWithFallbacks, InferFeatures } from '@supashiphq/react-sdk'
+ *
+ * // ✅ Use satisfies to preserve literal types
+ * export const FEATURE_FLAGS = {
+ *   'dark-mode': false,
+ *   'ui-config': { variant: 'a' as const }
+ * } satisfies FeaturesWithFallbacks
+ *
+ * declare module '@supashiphq/react-sdk' {
+ *   interface Features extends InferFeatures<typeof FEATURE_FLAGS> {}
+ * }
+ * ```
+ */
+type InferFeatures<T extends FeaturesWithFallbacks> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * Interface to be augmented by users for type-safe feature flags.
+ * Use InferFeatures helper to enable type-safe feature access.
+ *
+ * @example
+ * ```ts
+ * // lib/features.ts
+ * import { FeaturesWithFallbacks, InferFeatures } from '@supashiphq/react-sdk'
+ *
+ * export const FEATURE_FLAGS = {
+ *   'dark-mode': false,
+ *   'ui-config': {
+ *     variant: 'a' as const,
+ *     showWelcome: true,
+ *   },
+ * } satisfies FeaturesWithFallbacks
+ *
+ * declare module '@supashiphq/react-sdk' {
+ *   interface Features extends InferFeatures<typeof FEATURE_FLAGS> {}
+ * }
+ * ```
+ */
+interface Features {
+}
+/**
+ * Return type for useFeature hook with proper typing based on feature key
+ */
+type TypedFeatures = keyof Features extends never ? {
+    [key: string]: Omit<QueryState<FeatureValue | null>, 'data'> & {
+        feature: FeatureValue | null;
+    };
+} : {
+    [K in keyof Features]: Omit<QueryState<Features[K]>, 'data'> & {
+        feature: Features[K];
+    };
+};
+type FeatureKey = keyof Features extends never ? string : keyof Features;
+interface UseFeatureOptions {
+    context?: FeatureContext;
+    shouldFetch?: boolean;
+}
+interface UseFeaturesOptions {
+    context?: FeatureContext;
+    shouldFetch?: boolean;
+}
+
+interface UseFeatureResult<T extends FeatureValue> extends Omit<QueryState<T | null>, 'data'> {
+    feature: T | null;
+}
+interface UseFeaturesResult<T extends Record<string, FeatureValue>> extends Omit<QueryState<T>, 'data'> {
+    features: T;
+}
+/**
+ * Returns the state of a given feature for the current context.
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   const { feature, isLoading } = useFeature('my-feature')
+ *   if (isLoading) return <div>Loading...</div>
+ *   return <div>Feature value: {String(feature)}</div>
+ * }
+ * ```
+ *
+ * @remarks
+ * For type-safe feature flags, augment the Features interface:
+ * ```ts
+ * declare module '@supashiphq/react-sdk' {
+ *   interface Features {
+ *     'my-feature': { value: 'variant-a' | 'variant-b' }
+ *     'dark-mode': { value: boolean }
+ *   }
+ * }
+ *
+ * // Now get full type safety:
+ * const { feature } = useFeature('my-feature')
+ * // feature is typed as 'variant-a' | 'variant-b'
+ * ```
+ */
+declare function useFeature<TKey extends FeatureKey>(key: TKey, options?: {
+    context?: FeatureContext;
+    shouldFetch?: boolean;
+}): TypedFeatures[TKey];
+/**
+ * Extract feature value type from Features interface
+ */
+type ExtractFeatureValue<T> = T extends {
+    value: infer V;
+} ? V : FeatureValue;
+/**
+ * Returns the state of multiple features for the current context.
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   const { features, isLoading } = useFeatures(['feature-a', 'feature-b'])
+ *   if (isLoading) return <div>Loading...</div>
+ *   return <div>Feature A: {String(features['feature-a'])}</div>
+ * }
+ * ```
+ */
+declare function useFeatures<TKeys extends readonly FeatureKey[]>(featureNames: TKeys, options?: {
+    context?: FeatureContext;
+    shouldFetch?: boolean;
+}): UseFeaturesResult<{
+    [K in TKeys[number]]: K extends keyof Features ? ExtractFeatureValue<Features[K]> : FeatureValue | null;
+}>;
+
+interface SupaContextValue<TFeatures extends Features$1<Record<string, FeatureValue>>> {
+    client: SupaClient<TFeatures>;
+    updateContext: (context: FeatureContext, mergeWithExisting?: boolean) => void;
+    getContext: () => FeatureContext | undefined;
+}
+interface SupaProviderProps<TFeatures extends Features$1<Record<string, FeatureValue>>> {
+    config: Omit<SupaClientConfig, 'plugins' | 'toolbar'> & {
+        features: TFeatures;
+    };
+    toolbar?: SupaToolbarPluginConfig | boolean;
+    children: ReactNode;
+}
+declare function SupaProvider<TFeatures extends Features$1<Record<string, FeatureValue>>>({ config, toolbar, children, }: SupaProviderProps<TFeatures>): React.JSX.Element;
+declare function useClient<TFeatures extends Features$1<Record<string, FeatureValue>>>(): SupaClient<TFeatures>;
+/**
+ * Hook to update the context dynamically
+ * Useful when context depends on authentication or other async operations
+ */
+declare function useFeatureContext(): Omit<SupaContextValue<any>, 'client'>;
+
+interface SupaFeatureProps {
+    /**
+     * The feature flag key to evaluate
+     */
+    feature: FeatureKey;
+    /**
+     * Context for feature evaluation
+     */
+    context?: FeatureContext;
+    /**
+     * Whether to fetch the feature (default: true)
+     */
+    shouldFetch?: boolean;
+    /**
+     * Variations object mapping feature values/keys to JSX elements
+     */
+    variations: Record<string, ReactNode>;
+    /**
+     * Key in variations object to use for loading state
+     */
+    loading?: string;
+}
+/**
+ * SupaFeature component that conditionally renders variations based on feature flag values.
+ * Uses the default value defined in the client configuration.
+ *
+ * @example
+ * ```tsx
+ * <SupaFeature
+ *   feature="new-header"
+ *   variations={{
+ *     "true": <NewHeader />,
+ *     "false": <OldHeader />,
+ *     loading: <HeaderSkeleton />
+ *   }}
+ * />
+ * ```
+ */
+declare function SupaFeature({ feature, context, shouldFetch, variations, loading, }: SupaFeatureProps): React.JSX.Element | null;
+
+export { type BaseQueryState, type FeatureKey, type Features, type InferFeatures, QueryClient, type QueryKey, type QueryState, type QueryStatus, SupaFeature, type SupaFeatureProps, SupaProvider, type TypedFeatures, type UseFeatureOptions, type UseFeatureResult, type UseFeaturesOptions, type UseFeaturesResult, type UseQueryOptions, getInitialQueryState, queryCache, useClient, useFeature, useFeatureContext, useFeatures, useQuery, useQueryClient };