@savvagent/solid 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -1,10 +1,39 @@
 import * as solid_js from 'solid-js';
 import { ParentProps, Accessor } from 'solid-js';
 import { FlagClientConfig, FlagClient, FlagContext, FlagEvaluationResult } from '@savvagent/sdk';
-export { ApiTypes, ErrorEvent, EvaluationEvent, FlagClient, FlagClientConfig, FlagContext, FlagEvaluationResult, FlagUpdateEvent, components } from '@savvagent/sdk';
+export { ApiTypes, ErrorEvent, EvaluationEvent, FlagClient, FlagClientConfig, FlagContext, FlagDefinition, FlagEvaluationResult, FlagUpdateEvent, components } from '@savvagent/sdk';
 
+/**
+ * Default context values that apply to all flag evaluations
+ * Per SDK Developer Guide: https://docs.savvagent.com/sdk-developer-guide
+ */
+interface DefaultFlagContext {
+    /** Application ID for application-scoped flags */
+    applicationId?: string;
+    /** Environment (development, staging, production) */
+    environment?: string;
+    /** Organization ID for multi-tenant apps */
+    organizationId?: string;
+    /** Default user ID (required for percentage rollouts) */
+    userId?: string;
+    /** Default anonymous ID (alternative to userId for anonymous users) */
+    anonymousId?: string;
+    /** Session ID as fallback identifier */
+    sessionId?: string;
+    /** User's language code (e.g., "en", "es") */
+    language?: string;
+    /** Default attributes for targeting */
+    attributes?: Record<string, any>;
+}
+interface SavvagentContextValue {
+    client: FlagClient;
+    isReady: Accessor<boolean>;
+    defaultContext: Accessor<FlagContext>;
+}
 interface SavvagentProviderProps extends ParentProps {
     config: FlagClientConfig;
+    /** Default context values applied to all flag evaluations */
+    defaultContext?: DefaultFlagContext;
 }
 /**
  * Provider component that initializes and provides the Savvagent client.
@@ -15,7 +44,15 @@ interface SavvagentProviderProps extends ParentProps {
  *
  * function App() {
  *   return (
- *     <SavvagentProvider config={{ apiKey: 'sdk_...' }}>
+ *     <SavvagentProvider
+ *       config={{ apiKey: 'sdk_...' }}
+ *       defaultContext={{
+ *         applicationId: 'my-app-id',
+ *         environment: 'development',
+ *         userId: 'user-123',
+ *         attributes: { plan: 'pro' }
+ *       }}
+ *     >
  *       <MyApp />
  *     </SavvagentProvider>
  *   );
@@ -24,10 +61,10 @@ interface SavvagentProviderProps extends ParentProps {
  */
 declare function SavvagentProvider(props: SavvagentProviderProps): solid_js.JSX.Element;
 /**
- * Get the Savvagent client instance.
+ * Get the Savvagent context including client, ready state, and default context.
  * Must be used within a SavvagentProvider.
  *
- * @returns The FlagClient instance
+ * @returns The FlagClient instance, ready state accessor, and default context accessor
  * @throws Error if used outside of SavvagentProvider
  *
  * @example
@@ -35,13 +72,17 @@ declare function SavvagentProvider(props: SavvagentProviderProps): solid_js.JSX.
  * import { useSavvagent } from '@savvagent/solid';
  *
  * function MyComponent() {
- *   const client = useSavvagent();
- *   const enabled = await client.isEnabled('my-feature');
- *   return <div>Enabled: {enabled}</div>;
+ *   const { client, isReady, defaultContext } = useSavvagent();
+ *
+ *   return (
+ *     <Show when={isReady()}>
+ *       <div>Client ready!</div>
+ *     </Show>
+ *   );
  * }
  * ```
  */
-declare function useSavvagent(): FlagClient;
+declare function useSavvagent(): SavvagentContextValue;
 interface CreateFlagOptions {
     /** Context for flag evaluation */
     context?: FlagContext;
@@ -118,34 +159,209 @@ declare function createFlag(flagKey: string, options?: CreateFlagOptions): Creat
  * ```
  */
 declare function createFlagValue(flagKey: string, options?: CreateFlagOptions): Accessor<boolean>;
+interface CreateFlagsOptions {
+    /** Context for flag evaluation */
+    context?: FlagContext;
+    /** Default values for flags (keyed by flag key) */
+    defaultValues?: Record<string, boolean>;
+    /** Enable real-time updates */
+    realtime?: boolean;
+    /** Custom error handler */
+    onError?: (error: Error, flagKey: string) => void;
+}
+interface CreateFlagsReturn {
+    /** Map of flag keys to their current values */
+    values: Accessor<Record<string, boolean>>;
+    /** Whether any flag is currently being evaluated */
+    loading: Accessor<boolean>;
+    /** Map of flag keys to their errors (if any) */
+    errors: Accessor<Record<string, Error | null>>;
+    /** Map of flag keys to their detailed evaluation results */
+    results: Accessor<Record<string, FlagEvaluationResult | null>>;
+    /** Force re-evaluation of all flags */
+    refetch: () => void;
+}
 /**
- * Create signals for user identification.
+ * Create reactive flags for multiple flag keys with a single state update.
+ * This is more efficient than using multiple createFlag calls when you need
+ * several flags in the same component.
  *
- * @returns User ID management functions
+ * @param flagKeys - Array of feature flag keys to evaluate
+ * @param options - Configuration options
+ * @returns Reactive flag state for all flags
  *
  * @example
  * ```tsx
- * import { createUserSignals } from '@savvagent/solid';
+ * import { createFlags } from '@savvagent/solid';
+ * import { Show, For } from 'solid-js';
+ *
+ * function MyComponent() {
+ *   const flags = createFlags(
+ *     ['feature-a', 'feature-b', 'feature-c'],
+ *     {
+ *       context: { user_id: 'user-123' },
+ *       defaultValues: { 'feature-a': false, 'feature-b': true },
+ *       realtime: true
+ *     }
+ *   );
+ *
+ *   return (
+ *     <Show when={!flags.loading()} fallback={<Spinner />}>
+ *       <div>
+ *         <Show when={flags.values()['feature-a']}>
+ *           <FeatureA />
+ *         </Show>
+ *         <Show when={flags.values()['feature-b']}>
+ *           <FeatureB />
+ *         </Show>
+ *       </div>
+ *     </Show>
+ *   );
+ * }
+ * ```
+ */
+declare function createFlags(flagKeys: string[], options?: CreateFlagsOptions): CreateFlagsReturn;
+/**
+ * Execute a callback conditionally based on a flag value.
+ *
+ * @param flagKey - The feature flag key to check
+ * @param callback - Function to execute if flag is enabled
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * import { createWithFlag } from '@savvagent/solid';
+ *
+ * function MyComponent() {
+ *   createWithFlag('analytics-enabled', async () => {
+ *     await trackEvent('page_view');
+ *   });
+ *
+ *   return <div>Content</div>;
+ * }
+ * ```
+ */
+declare function createWithFlag(flagKey: string, callback: () => void | Promise<void>, options?: CreateFlagOptions): void;
+interface CreateUserReturn {
+    /** Current user ID */
+    userId: Accessor<string | null>;
+    /** Set user ID */
+    setUserId: (id: string | null) => void;
+    /** Get current user ID from client */
+    getUserId: () => string | null;
+    /** Current anonymous ID */
+    anonymousId: Accessor<string | null>;
+    /** Set anonymous ID */
+    setAnonymousId: (id: string) => void;
+    /** Get current anonymous ID from client */
+    getAnonymousId: () => string | null;
+}
+/**
+ * Create signals for user identification management.
+ *
+ * @returns User ID management functions and reactive signals
+ *
+ * @example
+ * ```tsx
+ * import { createUser } from '@savvagent/solid';
  * import { createEffect } from 'solid-js';
  *
  * function AuthHandler() {
- *   const [userId, setUserId] = createUserSignals();
+ *   const user = createUser();
  *
  *   createEffect(() => {
  *     if (currentUser()) {
- *       setUserId(currentUser().id);
+ *       user.setUserId(currentUser().id);
  *     } else {
- *       setUserId(null);
+ *       user.setUserId(null);
  *     }
  *   });
  *
- *   return null;
+ *   return <div>User ID: {user.userId()}</div>;
+ * }
+ * ```
+ */
+declare function createUser(): CreateUserReturn;
+interface CreateEnvironmentReturn {
+    /** Current environment as a reactive signal */
+    environment: Accessor<string>;
+    /** Set the environment */
+    setEnvironment: (env: string) => void;
+    /** Get the current environment from client */
+    getEnvironment: () => string;
+}
+/**
+ * Create signals for environment management.
+ *
+ * @returns Environment management functions and reactive signal
+ *
+ * @example
+ * ```tsx
+ * import { createEnvironment } from '@savvagent/solid';
+ *
+ * function EnvironmentSwitcher() {
+ *   const { environment, setEnvironment } = createEnvironment();
+ *
+ *   return (
+ *     <select value={environment()} onChange={(e) => setEnvironment(e.target.value)}>
+ *       <option value="development">Development</option>
+ *       <option value="staging">Staging</option>
+ *       <option value="production">Production</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+declare function createEnvironment(): CreateEnvironmentReturn;
+/**
+ * Legacy function - use createUser() instead.
+ * Create signals for user identification.
+ *
+ * @returns User ID signal tuple [userId, setUserId]
+ * @deprecated Use createUser() for full user management
+ *
+ * @example
+ * ```tsx
+ * import { createUserSignals } from '@savvagent/solid';
+ *
+ * function AuthHandler() {
+ *   const [userId, setUserId] = createUserSignals();
+ *
+ *   return <div>User ID: {userId()}</div>;
  * }
  * ```
  */
 declare function createUserSignals(): readonly [Accessor<string | null>, (id: string | null) => void];
+/**
+ * Create an error tracking function for a specific flag.
+ *
+ * @param flagKey - The flag key associated with errors
+ * @param context - Optional context
+ * @returns Error tracking function
+ *
+ * @example
+ * ```tsx
+ * import { createTrackError } from '@savvagent/solid';
+ *
+ * function FeatureComponent() {
+ *   const trackError = createTrackError('new-feature');
+ *
+ *   const handleAction = async () => {
+ *     try {
+ *       await doSomething();
+ *     } catch (error) {
+ *       trackError(error as Error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleAction}>Try Feature</button>;
+ * }
+ * ```
+ */
+declare function createTrackError(flagKey: string, context?: FlagContext): (error: Error) => void;
 /**
  * Track an error with flag context.
+ * Direct function call (not reactive).
  *
  * @param flagKey - The flag key associated with the error
  * @param error - The error that occurred
@@ -170,4 +386,4 @@ declare function createUserSignals(): readonly [Accessor<string | null>, (id: st
  */
 declare function trackError(flagKey: string, error: Error, context?: FlagContext): void;
 
-export { type CreateFlagOptions, type CreateFlagReturn, SavvagentProvider, type SavvagentProviderProps, createFlag, createFlagValue, createUserSignals, trackError, useSavvagent };
+export { type CreateEnvironmentReturn, type CreateFlagOptions, type CreateFlagReturn, type CreateFlagsOptions, type CreateFlagsReturn, type CreateUserReturn, type DefaultFlagContext, SavvagentProvider, type SavvagentProviderProps, createEnvironment, createFlag, createFlagValue, createFlags, createTrackError, createUser, createUserSignals, createWithFlag, trackError, useSavvagent };

package/dist/index.d.ts

@@ -1,10 +1,39 @@
 import * as solid_js from 'solid-js';
 import { ParentProps, Accessor } from 'solid-js';
 import { FlagClientConfig, FlagClient, FlagContext, FlagEvaluationResult } from '@savvagent/sdk';
-export { ApiTypes, ErrorEvent, EvaluationEvent, FlagClient, FlagClientConfig, FlagContext, FlagEvaluationResult, FlagUpdateEvent, components } from '@savvagent/sdk';
+export { ApiTypes, ErrorEvent, EvaluationEvent, FlagClient, FlagClientConfig, FlagContext, FlagDefinition, FlagEvaluationResult, FlagUpdateEvent, components } from '@savvagent/sdk';
 
+/**
+ * Default context values that apply to all flag evaluations
+ * Per SDK Developer Guide: https://docs.savvagent.com/sdk-developer-guide
+ */
+interface DefaultFlagContext {
+    /** Application ID for application-scoped flags */
+    applicationId?: string;
+    /** Environment (development, staging, production) */
+    environment?: string;
+    /** Organization ID for multi-tenant apps */
+    organizationId?: string;
+    /** Default user ID (required for percentage rollouts) */
+    userId?: string;
+    /** Default anonymous ID (alternative to userId for anonymous users) */
+    anonymousId?: string;
+    /** Session ID as fallback identifier */
+    sessionId?: string;
+    /** User's language code (e.g., "en", "es") */
+    language?: string;
+    /** Default attributes for targeting */
+    attributes?: Record<string, any>;
+}
+interface SavvagentContextValue {
+    client: FlagClient;
+    isReady: Accessor<boolean>;
+    defaultContext: Accessor<FlagContext>;
+}
 interface SavvagentProviderProps extends ParentProps {
     config: FlagClientConfig;
+    /** Default context values applied to all flag evaluations */
+    defaultContext?: DefaultFlagContext;
 }
 /**
  * Provider component that initializes and provides the Savvagent client.
@@ -15,7 +44,15 @@ interface SavvagentProviderProps extends ParentProps {
  *
  * function App() {
  *   return (
- *     <SavvagentProvider config={{ apiKey: 'sdk_...' }}>
+ *     <SavvagentProvider
+ *       config={{ apiKey: 'sdk_...' }}
+ *       defaultContext={{
+ *         applicationId: 'my-app-id',
+ *         environment: 'development',
+ *         userId: 'user-123',
+ *         attributes: { plan: 'pro' }
+ *       }}
+ *     >
  *       <MyApp />
  *     </SavvagentProvider>
  *   );
@@ -24,10 +61,10 @@ interface SavvagentProviderProps extends ParentProps {
  */
 declare function SavvagentProvider(props: SavvagentProviderProps): solid_js.JSX.Element;
 /**
- * Get the Savvagent client instance.
+ * Get the Savvagent context including client, ready state, and default context.
  * Must be used within a SavvagentProvider.
  *
- * @returns The FlagClient instance
+ * @returns The FlagClient instance, ready state accessor, and default context accessor
  * @throws Error if used outside of SavvagentProvider
  *
  * @example
@@ -35,13 +72,17 @@ declare function SavvagentProvider(props: SavvagentProviderProps): solid_js.JSX.
  * import { useSavvagent } from '@savvagent/solid';
  *
  * function MyComponent() {
- *   const client = useSavvagent();
- *   const enabled = await client.isEnabled('my-feature');
- *   return <div>Enabled: {enabled}</div>;
+ *   const { client, isReady, defaultContext } = useSavvagent();
+ *
+ *   return (
+ *     <Show when={isReady()}>
+ *       <div>Client ready!</div>
+ *     </Show>
+ *   );
  * }
  * ```
  */
-declare function useSavvagent(): FlagClient;
+declare function useSavvagent(): SavvagentContextValue;
 interface CreateFlagOptions {
     /** Context for flag evaluation */
     context?: FlagContext;
@@ -118,34 +159,209 @@ declare function createFlag(flagKey: string, options?: CreateFlagOptions): Creat
  * ```
  */
 declare function createFlagValue(flagKey: string, options?: CreateFlagOptions): Accessor<boolean>;
+interface CreateFlagsOptions {
+    /** Context for flag evaluation */
+    context?: FlagContext;
+    /** Default values for flags (keyed by flag key) */
+    defaultValues?: Record<string, boolean>;
+    /** Enable real-time updates */
+    realtime?: boolean;
+    /** Custom error handler */
+    onError?: (error: Error, flagKey: string) => void;
+}
+interface CreateFlagsReturn {
+    /** Map of flag keys to their current values */
+    values: Accessor<Record<string, boolean>>;
+    /** Whether any flag is currently being evaluated */
+    loading: Accessor<boolean>;
+    /** Map of flag keys to their errors (if any) */
+    errors: Accessor<Record<string, Error | null>>;
+    /** Map of flag keys to their detailed evaluation results */
+    results: Accessor<Record<string, FlagEvaluationResult | null>>;
+    /** Force re-evaluation of all flags */
+    refetch: () => void;
+}
 /**
- * Create signals for user identification.
+ * Create reactive flags for multiple flag keys with a single state update.
+ * This is more efficient than using multiple createFlag calls when you need
+ * several flags in the same component.
  *
- * @returns User ID management functions
+ * @param flagKeys - Array of feature flag keys to evaluate
+ * @param options - Configuration options
+ * @returns Reactive flag state for all flags
  *
  * @example
  * ```tsx
- * import { createUserSignals } from '@savvagent/solid';
+ * import { createFlags } from '@savvagent/solid';
+ * import { Show, For } from 'solid-js';
+ *
+ * function MyComponent() {
+ *   const flags = createFlags(
+ *     ['feature-a', 'feature-b', 'feature-c'],
+ *     {
+ *       context: { user_id: 'user-123' },
+ *       defaultValues: { 'feature-a': false, 'feature-b': true },
+ *       realtime: true
+ *     }
+ *   );
+ *
+ *   return (
+ *     <Show when={!flags.loading()} fallback={<Spinner />}>
+ *       <div>
+ *         <Show when={flags.values()['feature-a']}>
+ *           <FeatureA />
+ *         </Show>
+ *         <Show when={flags.values()['feature-b']}>
+ *           <FeatureB />
+ *         </Show>
+ *       </div>
+ *     </Show>
+ *   );
+ * }
+ * ```
+ */
+declare function createFlags(flagKeys: string[], options?: CreateFlagsOptions): CreateFlagsReturn;
+/**
+ * Execute a callback conditionally based on a flag value.
+ *
+ * @param flagKey - The feature flag key to check
+ * @param callback - Function to execute if flag is enabled
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * import { createWithFlag } from '@savvagent/solid';
+ *
+ * function MyComponent() {
+ *   createWithFlag('analytics-enabled', async () => {
+ *     await trackEvent('page_view');
+ *   });
+ *
+ *   return <div>Content</div>;
+ * }
+ * ```
+ */
+declare function createWithFlag(flagKey: string, callback: () => void | Promise<void>, options?: CreateFlagOptions): void;
+interface CreateUserReturn {
+    /** Current user ID */
+    userId: Accessor<string | null>;
+    /** Set user ID */
+    setUserId: (id: string | null) => void;
+    /** Get current user ID from client */
+    getUserId: () => string | null;
+    /** Current anonymous ID */
+    anonymousId: Accessor<string | null>;
+    /** Set anonymous ID */
+    setAnonymousId: (id: string) => void;
+    /** Get current anonymous ID from client */
+    getAnonymousId: () => string | null;
+}
+/**
+ * Create signals for user identification management.
+ *
+ * @returns User ID management functions and reactive signals
+ *
+ * @example
+ * ```tsx
+ * import { createUser } from '@savvagent/solid';
  * import { createEffect } from 'solid-js';
  *
  * function AuthHandler() {
- *   const [userId, setUserId] = createUserSignals();
+ *   const user = createUser();
  *
  *   createEffect(() => {
  *     if (currentUser()) {
- *       setUserId(currentUser().id);
+ *       user.setUserId(currentUser().id);
  *     } else {
- *       setUserId(null);
+ *       user.setUserId(null);
  *     }
  *   });
  *
- *   return null;
+ *   return <div>User ID: {user.userId()}</div>;
+ * }
+ * ```
+ */
+declare function createUser(): CreateUserReturn;
+interface CreateEnvironmentReturn {
+    /** Current environment as a reactive signal */
+    environment: Accessor<string>;
+    /** Set the environment */
+    setEnvironment: (env: string) => void;
+    /** Get the current environment from client */
+    getEnvironment: () => string;
+}
+/**
+ * Create signals for environment management.
+ *
+ * @returns Environment management functions and reactive signal
+ *
+ * @example
+ * ```tsx
+ * import { createEnvironment } from '@savvagent/solid';
+ *
+ * function EnvironmentSwitcher() {
+ *   const { environment, setEnvironment } = createEnvironment();
+ *
+ *   return (
+ *     <select value={environment()} onChange={(e) => setEnvironment(e.target.value)}>
+ *       <option value="development">Development</option>
+ *       <option value="staging">Staging</option>
+ *       <option value="production">Production</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+declare function createEnvironment(): CreateEnvironmentReturn;
+/**
+ * Legacy function - use createUser() instead.
+ * Create signals for user identification.
+ *
+ * @returns User ID signal tuple [userId, setUserId]
+ * @deprecated Use createUser() for full user management
+ *
+ * @example
+ * ```tsx
+ * import { createUserSignals } from '@savvagent/solid';
+ *
+ * function AuthHandler() {
+ *   const [userId, setUserId] = createUserSignals();
+ *
+ *   return <div>User ID: {userId()}</div>;
  * }
  * ```
  */
 declare function createUserSignals(): readonly [Accessor<string | null>, (id: string | null) => void];
+/**
+ * Create an error tracking function for a specific flag.
+ *
+ * @param flagKey - The flag key associated with errors
+ * @param context - Optional context
+ * @returns Error tracking function
+ *
+ * @example
+ * ```tsx
+ * import { createTrackError } from '@savvagent/solid';
+ *
+ * function FeatureComponent() {
+ *   const trackError = createTrackError('new-feature');
+ *
+ *   const handleAction = async () => {
+ *     try {
+ *       await doSomething();
+ *     } catch (error) {
+ *       trackError(error as Error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleAction}>Try Feature</button>;
+ * }
+ * ```
+ */
+declare function createTrackError(flagKey: string, context?: FlagContext): (error: Error) => void;
 /**
  * Track an error with flag context.
+ * Direct function call (not reactive).
  *
  * @param flagKey - The flag key associated with the error
  * @param error - The error that occurred
@@ -170,4 +386,4 @@ declare function createUserSignals(): readonly [Accessor<string | null>, (id: st
  */
 declare function trackError(flagKey: string, error: Error, context?: FlagContext): void;
 
-export { type CreateFlagOptions, type CreateFlagReturn, SavvagentProvider, type SavvagentProviderProps, createFlag, createFlagValue, createUserSignals, trackError, useSavvagent };
+export { type CreateEnvironmentReturn, type CreateFlagOptions, type CreateFlagReturn, type CreateFlagsOptions, type CreateFlagsReturn, type CreateUserReturn, type DefaultFlagContext, SavvagentProvider, type SavvagentProviderProps, createEnvironment, createFlag, createFlagValue, createFlags, createTrackError, createUser, createUserSignals, createWithFlag, trackError, useSavvagent };