@hyphen/sdk 1.12.2 → 2.0.0

package/dist/index.d.ts

@@ -1,9 +1,7 @@
 import { HookifiedOptions, Hookified } from 'hookified';
-import * as axios from 'axios';
-import { AxiosRequestConfig } from 'axios';
+import { FetchRequestInit, FetchOptions } from '@cacheable/net';
 import { Cacheable } from 'cacheable';
 import pino from 'pino';
-import { EvaluationContext, Client } from '@openfeature/server-sdk';
 
 type EnvOptions = {
     path?: string;
@@ -23,6 +21,14 @@ declare function env(options?: EnvOptions): void;
 declare const loadEnv: typeof env;
 type LoadEnvOptions = EnvOptions;
 
+interface HttpResponse<T = any> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: any;
+    config: any;
+    request?: any;
+}
 type BaseServiceOptions = {
     throwErrors?: boolean;
 } & HookifiedOptions;
@@ -30,6 +36,7 @@ declare class BaseService extends Hookified {
     private _log;
     private _cache;
     private _throwErrors;
+    private _net;
     constructor(options?: BaseServiceOptions);
     get log(): pino.Logger;
     set log(value: pino.Logger);
@@ -40,11 +47,15 @@ declare class BaseService extends Hookified {
     error(message: string, ...args: any[]): void;
     warn(message: string, ...args: any[]): void;
     info(message: string, ...args: any[]): void;
-    get<T>(url: string, config?: AxiosRequestConfig): Promise<axios.AxiosResponse<T, any, {}>>;
-    post<T>(url: string, data: any, config?: AxiosRequestConfig): Promise<axios.AxiosResponse<T, any, {}>>;
-    put<T>(url: string, data: any, config?: AxiosRequestConfig): Promise<axios.AxiosResponse<T, any, {}>>;
-    delete<T>(url: string, config?: AxiosRequestConfig): Promise<axios.AxiosResponse<T, any, {}>>;
-    patch<T>(url: string, data: any, config?: AxiosRequestConfig): Promise<axios.AxiosResponse<T, any, {}>>;
+    get<T>(url: string, config?: FetchRequestInit & {
+        params?: any;
+    }): Promise<HttpResponse<T>>;
+    post<T>(url: string, data: any, config?: FetchRequestInit): Promise<HttpResponse<T>>;
+    put<T>(url: string, data: any, config?: FetchRequestInit): Promise<HttpResponse<T>>;
+    delete<T>(url: string, config?: FetchRequestInit & {
+        data?: any;
+    }): Promise<HttpResponse<T>>;
+    patch<T>(url: string, data: any, config?: FetchRequestInit): Promise<HttpResponse<T>>;
     createHeaders(apiKey?: string): Record<string, string>;
 }
 
@@ -386,205 +397,569 @@ declare class NetInfo extends BaseService {
     getIpInfos(ips: string[]): Promise<Array<ipInfo | ipInfoError>>;
 }
 
-type ToggleContext = EvaluationContext;
-declare enum ToggleHooks {
-    beforeGetBoolean = "beforeGetBoolean",
-    afterGetBoolean = "afterGetBoolean",
-    beforeGetString = "beforeGetString",
-    afterGetString = "afterGetString",
-    beforeGetNumber = "beforeGetNumber",
-    afterGetNumber = "afterGetNumber",
-    beforeGetObject = "beforeGetObject",
-    afterGetObject = "afterGetObject"
-}
-type ToggleCachingOptions = {
-    ttl?: number;
-    generateCacheKeyFn?: (context?: ToggleContext) => string;
-};
-type ToggleOptions = {
+/**
+ * Custom attributes that can contain any key-value pairs.
+ */
+type CustomAttributes = Record<string, unknown>;
+/**
+ * User information for evaluation context.
+ */
+type ToggleUser = {
     /**
-     * Your application name. If this is not set it will look for the HYPHEN_APPLICATION_ID environment variable.
-     * @type {string}
+     * Unique identifier for the user.
      */
-    applicationId?: string;
+    id: string;
     /**
-     * Your Hyphen Public API key. If this is not set it will look for the HYPHEN_PUBLIC_API_KEY environment variable.
-     * @type {string}
+     * User's email address.
      */
-    publicApiKey?: string;
+    email?: string;
     /**
-     * Your environment name such as development, production. Default is what is set at NODE_ENV
-     * @type {string}
-     * @example production
+     * User's display name.
      */
-    environment?: string;
+    name?: string;
     /**
-     * The context to use for evaluating feature flags
-     * @type {ToggleContext}
+     * Custom attributes specific to the user.
      */
-    context?: ToggleContext;
+    customAttributes?: CustomAttributes;
+};
+/**
+ * Evaluation context for Hyphen feature toggle evaluation.
+ *
+ * @example
+ * ```typescript
+ * const context: ToggleContext = {
+ *   targetingKey: "user-123",
+ *   ipAddress: "203.0.113.42",
+ *   customAttributes: {
+ *     subscriptionLevel: "premium",
+ *     region: "us-east",
+ *   },
+ *   user: {
+ *     id: "user-123",
+ *     email: "john.doe@example.com",
+ *     name: "John Doe",
+ *     customAttributes: {
+ *       role: "admin",
+ *     },
+ *   },
+ * };
+ * ```
+ */
+type ToggleContext = {
     /**
-     * Cache options to use for the request
-     * @type {ToggleCachingOptions}
+     * Primary key used for targeting and bucketing.
      */
-    caching?: ToggleCachingOptions;
+    targetingKey?: string;
     /**
-     * Throw errors in addition to emitting them
-     * @type {boolean}
-     * @default false
+     * IP address of the user making the request.
      */
-    throwErrors?: boolean;
+    ipAddress?: string;
     /**
-     * Horizon URIs to use for talking to Toggle. You can use this to override
-     * the default URIs for testin or if you are using a self-hosted version.
-     * @type {Array<string>}
-     * @example ['https://toggle.hyphen.ai']
+     * Custom attributes for evaluation context.
      */
-    uris?: string[];
-};
-type ToggleGetOptions = {
+    customAttributes?: CustomAttributes;
     /**
-     * The context to use for evaluating feature flags
-     * @type {ToggleContext}
+     * User information for evaluation.
      */
-    context?: ToggleContext;
+    user?: ToggleUser;
 };
-declare class Toggle extends Hookified {
-    private _applicationId;
-    private _publicApiKey;
-    private _environment;
-    private _client;
-    private _context;
-    private _throwErrors;
-    private _uris;
-    private _caching;
-    constructor(options?: ToggleOptions);
+/**
+ * Internal type combining application info with toggle context for evaluation.
+ */
+type ToggleEvaluation = {
+    application: string;
+    environment: string;
+} & ToggleContext;
+/**
+ * Options for toggle getter methods.
+ */
+type GetOptions = {
     /**
-     * Get the application ID
-     * @returns {string | undefined}
+     * Override the default context for this request.
      */
-    get applicationId(): string | undefined;
+    context?: ToggleContext;
     /**
-     * Set the application ID
-     * @param {string | undefined} value
+     * Whether to use caching for this request (if caching is configured).
      */
-    set applicationId(value: string | undefined);
+    cache?: boolean;
+};
+/**
+ * Events emitted by the Toggle class.
+ */
+declare enum ToggleEvents {
     /**
-     * Get the public API key
-     * @returns {string}
+     * Emitted when an error occurs during toggle evaluation.
      */
-    get publicApiKey(): string | undefined;
+    Error = "error"
+}
+/**
+ * Configuration options for the Toggle class.
+ */
+type ToggleOptions = {
     /**
-     * Set the public API key
-     * @param {string} value
+     * Public API key for authentication.
+     * Can be found in your Hyphen dashboard.
+     * Must start with "public_".
      */
-    set publicApiKey(value: string | undefined);
+    publicApiKey?: string;
     /**
-     * Get the environment
-     * @returns {string}
+     * The default context to use when one is not passed to getter methods.
+     * Can be overridden per-request using the GetOptions parameter.
      */
-    get environment(): string;
+    defaultContext?: ToggleContext;
     /**
-     * Set the environment
-     * @param {string} value
+     * Horizon endpoint URLs for load balancing and failover.
+     * If provided, requests will be attempted in order. If all fail,
+     * defaults to Hyphen's hosted service.
+     * @see {@link https://hyphen.ai/horizon} for more information
      */
-    set environment(value: string);
+    horizonUrls?: string[];
     /**
-     * Get the throwErrors. If true, errors will be thrown in addition to being emitted.
-     * @returns {boolean}
+     * Application ID for your Hyphen project.
+     * Can be found in your Hyphen dashboard.
      */
-    get throwErrors(): boolean;
+    applicationId?: string;
     /**
-     * Set the throwErrors. If true, errors will be thrown in addition to being emitted.
-     * @param {boolean} value
+     * Environment name (e.g., "production", "development", "staging").
+     * Defaults to "development" if not provided.
      */
-    set throwErrors(value: boolean);
+    environment?: string;
     /**
-     * Get the current context. This is the default context used. You can override this at the get function level.
-     * @returns {ToggleContext}
+     * Default targeting key to use if one cannot be derived from context.
+     * If not provided, a random key will be generated.
      */
-    get context(): ToggleContext | undefined;
+    defaultTargetKey?: string;
+    cache?: Cacheable;
+};
+/**
+ * Toggle class for feature flag management with Hyphen.
+ *
+ * This class provides methods to retrieve feature toggle values with support for
+ * multiple value types (boolean, string, number, object), context-based targeting,
+ * and load-balanced requests across multiple Horizon endpoints.
+ *
+ * @extends Hookified - Provides event and hook system capabilities
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const toggle = new Toggle({
+ *   publicApiKey: 'public_your-key-here',
+ *   applicationId: 'app-123',
+ *   environment: 'production'
+ * });
+ *
+ * const isEnabled = await toggle.getBoolean('new-feature', false);
+ * ```
+ *
+ * @example
+ * With context:
+ * ```typescript
+ * const toggle = new Toggle({
+ *   publicApiKey: 'public_your-key-here',
+ *   applicationId: 'app-123',
+ *   defaultContext: {
+ *     targetingKey: 'user-456',
+ *     user: { id: 'user-456', email: 'user@example.com' }
+ *   }
+ * });
+ *
+ * const message = await toggle.getString('welcome-message', 'Hello!');
+ * ```
+ *
+ * @example
+ * With error handling:
+ * ```typescript
+ * const toggle = new Toggle({ publicApiKey: 'public_key', applicationId: 'app' });
+ *
+ * toggle.on('error', (error) => {
+ *   console.error('Toggle error:', error);
+ * });
+ *
+ * const value = await toggle.getNumber('max-items', 10);
+ * ```
+ */
+declare class Toggle extends Hookified {
+    private _publicApiKey?;
+    private _organizationId;
+    private _applicationId;
+    private _environment;
+    private _horizonUrls;
+    private _net;
+    private _defaultContext;
+    private _defaultTargetingKey;
+    /**
+     * Creates a new Toggle instance.
+     *
+     * @param options - Configuration options for the toggle client
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration
+     * const toggle = new Toggle({
+     *   publicApiKey: 'public_your-key',
+     *   applicationId: 'app-123'
+     * });
+     *
+     * // With full options
+     * const toggle = new Toggle({
+     *   publicApiKey: 'public_your-key',
+     *   applicationId: 'app-123',
+     *   environment: 'production',
+     *   defaultContext: { targetingKey: 'user-456' },
+     *   horizonUrls: ['https://my-horizon.example.com']
+     * });
+     * ```
+     */
+    constructor(options?: ToggleOptions);
     /**
-     * Set the context. This is the default context used. You can override this at the get function level.
-     * @param {ToggleContext} value
+     * Gets the public API key used for authentication.
+     *
+     * @returns The current public API key or undefined if not set
      */
-    set context(value: ToggleContext | undefined);
+    get publicApiKey(): string | undefined;
     /**
-     * Get the URIs. This is used to override the default URIs for testing or if you are using a self-hosted version.
-     * @returns {Array<string>}
+     * Sets the public API key used for authentication.
+     *
+     * @param value - The public API key string or undefined to clear
+     * @throws {Error} If the key doesn't start with "public_"
      */
-    get uris(): string[] | undefined;
+    set publicApiKey(value: string | undefined);
     /**
-     * Set the URIs. This is used to override the default URIs for testing or if you are using a self-hosted version.
-     * @param {Array<string>} value
+     * Gets the default context used for toggle evaluations.
+     *
+     * @returns The current default ToggleContext
      */
-    set uris(value: string[] | undefined);
+    get defaultContext(): ToggleContext | undefined;
     /**
-     * Get the caching options.
-     * @returns {ToggleCachingOptions | undefined}
+     * Sets the default context used for toggle evaluations.
+     *
+     * @param value - The ToggleContext to use as default
      */
-    get caching(): ToggleCachingOptions | undefined;
+    set defaultContext(value: ToggleContext);
     /**
-     * Set the caching options.
-     * @param {ToggleCachingOptions | undefined} value
+     * Gets the organization ID extracted from the public API key.
+     *
+     * @returns The organization ID string or undefined if not available
      */
-    set caching(value: ToggleCachingOptions | undefined);
+    get organizationId(): string | undefined;
     /**
-     * This is a helper function to set the public API key. It will check if the key starts with public_ and set it. If it
-     * does set it will also set the client to undefined to force a new one to be created. If it does not,
-     * it will emit an error and console warning and not set the key. Used by the constructor and publicApiKey setter.
-     * @param key
-     * @returns
+     * Gets the Horizon endpoint URLs used for load balancing.
+     *
+     * These URLs are used to distribute requests across multiple Horizon endpoints.
+     * If endpoints fail, the system will attempt to use the default horizon endpoint service.
+     *
+     * @returns Array of Horizon endpoint URLs
+     * @see {@link https://hyphen.ai/horizon} for more information
+     */
+    get horizonUrls(): string[];
+    /**
+     * Sets the Horizon endpoint URLs for load balancing.
+     *
+     * Configures multiple Horizon endpoints that will be used for load balancing.
+     * When endpoints fail, the system will fall back to the default horizon endpoint service.
+     *
+     * @param value - Array of Horizon endpoint URLs or empty array to clear
+     * @see {@link https://hyphen.ai/horizon} for more information
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle();
+     * toggle.horizonUrls = [
+     *   'https://org1.toggle.hyphen.cloud',
+     *   'https://org2.toggle.hyphen.cloud'
+     * ];
+     * ```
+     */
+    set horizonUrls(value: string[]);
+    /**
+     * Gets the application ID used for toggle context.
+     *
+     * @returns The current application ID or undefined if not set
      */
-    setPublicApiKey(key: string): void;
+    get applicationId(): string | undefined;
     /**
-     * Set the context. This is the default context used. You can override this at the get function level.
-     * @param {ToggleContext} context
+     * Sets the application ID used for toggle context.
+     *
+     * @param value - The application ID string or undefined to clear
      */
-    setContext(context: ToggleContext): void;
+    set applicationId(value: string | undefined);
     /**
-     * Helper function to get the client. This will create a new client if one does not exist. It will also set the
-     * application ID, environment, and URIs if they are not set. This is used by the get function to get the client.
-     * This is normally only used internally.
-     * @returns {Promise<Client>}
+     * Gets the environment used for toggle context.
+     *
+     * @returns The current environment (defaults to 'development')
      */
-    getClient(): Promise<Client>;
+    get environment(): string | undefined;
     /**
-     * This is the main function to get a feature flag value. It will check the type of the default value and call the
-     * appropriate function. It will also set the context if it is not set.
-     * @param {string} key - The key of the feature flag
-     * @param {T} defaultValue - The default value to return if the feature flag is not set or does not evaluate.
-     * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
-     * @returns {Promise<T>}
+     * Sets the environment used for toggle context.
+     *
+     * @param value - The environment string or undefined to clear
      */
-    get<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
+    set environment(value: string | undefined);
     /**
-     * Get a boolean value from the feature flag. This will check the type of the default value and call the
-     * appropriate function. It will also set the context if it is not set.
-     * @param {string} key - The key of the feature flag
-     * @param {boolean} defaultValue - The default value to return if the feature flag is not set or does not evaluate.
-     * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
-     * @returns {Promise<boolean>} - The value of the feature flag
+     * Gets the default targeting key used for toggle evaluations.
+     *
+     * @returns The current default targeting key or undefined if not set
      */
-    getBoolean(key: string, defaultValue: boolean, options?: ToggleGetOptions): Promise<boolean>;
+    get defaultTargetingKey(): string;
     /**
-     * Get a string value from the feature flag.
-     * @param {string} key - The key of the feature flag
-     * @param {string} defaultValue - The default value to return if the feature flag is not set or does not evaluate.
-     * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
-     * @returns {Promise<string>} - The value of the feature flag
+     * Sets the default targeting key used for toggle evaluations.
+     *
+     * @param value - The targeting key string or undefined to clear
      */
-    getString(key: string, defaultValue: string, options?: ToggleGetOptions): Promise<string>;
-    getNumber(key: string, defaultValue: number, options?: ToggleGetOptions): Promise<number>;
+    set defaultTargetingKey(value: string);
     /**
-     * Get an object value from the feature flag. This will check the type of the default value and call the
-     * appropriate function. It will also set the context if it is not set.
-     * @param {string} key - The key of the feature flag
-     * @param {T} defaultValue - The default value to return if the feature flag is not set or does not evaluate.
-     * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
-     * @returns {Promise<T>} - The value of the feature flag
+     * Gets the Cacheable instance used for caching fetch operations.
+     *
+     * @returns The current Cacheable instance
      */
-    getObject<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
+    get cache(): Cacheable;
+    /**
+     * Sets the Cacheable instance for caching fetch operations.
+     *
+     * @param cache - The Cacheable instance to use for caching
+     */
+    set cache(cache: Cacheable);
+    /**
+     * Retrieves a toggle value with generic type support.
+     *
+     * This is the core method for fetching toggle values. All convenience methods
+     * (getBoolean, getString, getNumber, getObject) delegate to this method.
+     *
+     * @template T - The expected type of the toggle value
+     * @param toggleKey - The key of the toggle to retrieve
+     * @param defaultValue - The value to return if the toggle is not found or an error occurs
+     * @param options - Optional configuration including context override
+     * @returns Promise resolving to the toggle value or defaultValue
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle({ publicApiKey: 'public_key', applicationId: 'app-id' });
+     *
+     * // Get a boolean
+     * const enabled = await toggle.get<boolean>('feature-flag', false);
+     *
+     * // Get an object with type safety
+     * interface Config { theme: string; }
+     * const config = await toggle.get<Config>('app-config', { theme: 'light' });
+     *
+     * // Override context for a single request
+     * const value = await toggle.get('key', 'default', {
+     *   context: { targetingKey: 'user-456' }
+     * });
+     * ```
+     */
+    get<T>(toggleKey: string, defaultValue: T, options?: GetOptions): Promise<T>;
+    /**
+     * Retrieves a boolean toggle value.
+     *
+     * This is a convenience method that wraps the generic get() method with boolean type safety.
+     *
+     * @param toggleKey - The key of the toggle to retrieve
+     * @param defaultValue - The boolean value to return if the toggle is not found or an error occurs
+     * @param options - Optional configuration including context for toggle evaluation
+     * @returns Promise resolving to the boolean toggle value or defaultValue
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle({ publicApiKey: 'public_key', applicationId: 'app-id' });
+     * const isFeatureEnabled = await toggle.getBoolean('feature-flag', false);
+     * console.log(isFeatureEnabled); // true or false
+     * ```
+     */
+    getBoolean(toggleKey: string, defaultValue: boolean, options?: GetOptions): Promise<boolean>;
+    /**
+     * Retrieves a string toggle value.
+     *
+     * This is a convenience method that wraps the generic get() method with string type safety.
+     *
+     * @param toggleKey - The key of the toggle to retrieve
+     * @param defaultValue - The string value to return if the toggle is not found or an error occurs
+     * @param options - Optional configuration including context for toggle evaluation
+     * @returns Promise resolving to the string toggle value or defaultValue
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle({ publicApiKey: 'public_key', applicationId: 'app-id' });
+     * const message = await toggle.getString('welcome-message', 'Hello World');
+     * console.log(message); // 'Welcome to our app!' or 'Hello World'
+     * ```
+     */
+    getString(toggleKey: string, defaultValue: string, options?: GetOptions): Promise<string>;
+    /**
+     * Retrieves an object toggle value.
+     *
+     * This is a convenience method that wraps the generic get() method with object type safety.
+     * Note that the toggle service may return JSON as a string, which should be parsed if needed.
+     *
+     * @template T - The expected object type
+     * @param toggleKey - The key of the toggle to retrieve
+     * @param defaultValue - The object value to return if the toggle is not found or an error occurs
+     * @param options - Optional configuration including context for toggle evaluation
+     * @returns Promise resolving to the object toggle value or defaultValue
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle({ publicApiKey: 'public_key', applicationId: 'app-id' });
+     * const config = await toggle.getObject('app-config', { theme: 'light' });
+     * console.log(config); // { theme: 'dark', features: ['a', 'b'] } or { theme: 'light' }
+     * ```
+     */
+    getObject<T extends object>(toggleKey: string, defaultValue: T, options?: GetOptions): Promise<T>;
+    /**
+     * Retrieves a number toggle value.
+     *
+     * This is a convenience method that wraps the generic get() method with number type safety.
+     *
+     * @param toggleKey - The key of the toggle to retrieve
+     * @param defaultValue - The number value to return if the toggle is not found or an error occurs
+     * @param options - Optional configuration including context for toggle evaluation
+     * @returns Promise resolving to the number toggle value or defaultValue
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle({ publicApiKey: 'public_key', applicationId: 'app-id' });
+     * const maxRetries = await toggle.getNumber('max-retries', 3);
+     * console.log(maxRetries); // 5 or 3
+     * ```
+     */
+    getNumber(toggleKey: string, defaultValue: number, options?: GetOptions): Promise<number>;
+    /**
+     * Makes an HTTP POST request to the specified URL with automatic authentication.
+     *
+     * This method uses browser-compatible fetch and automatically includes the
+     * public API key in the x-api-key header if available. It supports load
+     * balancing across multiple horizon URLs with fallback behavior.
+     *
+     * @template T - The expected response type
+     * @param path - The API path to request (e.g., '/api/toggles')
+     * @param payload - The JSON payload to send in the request body
+     * @param options - Optional fetch configuration. Cache is set at .cache
+     * @returns Promise resolving to the parsed JSON response
+     * @throws {Error} If no horizon URLs are configured or all requests fail
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle({
+     *   publicApiKey: 'public_your-key-here',
+     *   horizonUrls: ['https://api.hyphen.cloud']
+     * });
+     *
+     * interface ToggleResponse {
+     *   enabled: boolean;
+     *   value: string;
+     * }
+     *
+     * const result = await toggle.fetch<ToggleResponse>('/api/toggle/feature-flag', {
+     *   context: { targetingKey: 'user-123' }
+     * });
+     * console.log(result.enabled); // true/false
+     * ```
+     */
+    fetch<T>(path: string, payload?: unknown, options?: Omit<FetchOptions, "cache">): Promise<T>;
+    /**
+     * Validates and sets the public API key.
+     *
+     * This method is used internally by the publicApiKey setter to validate
+     * that the key starts with "public_" prefix. If the key is invalid,
+     * an error is thrown.
+     *
+     * @param key - The public API key string or undefined to clear
+     * @throws {Error} If the key doesn't start with "public_"
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle();
+     *
+     * // Valid key
+     * toggle.setPublicKey('public_abc123'); // OK
+     *
+     * // Invalid key
+     * toggle.setPublicKey('invalid_key'); // Throws error
+     *
+     * // Clear key
+     * toggle.setPublicKey(undefined); // OK
+     * ```
+     */
+    setPublicKey(key: string | undefined): void;
+    /**
+     * Extracts the organization ID from a public API key.
+     *
+     * The public key format is: `public_<base64-encoded-data>`
+     * The base64 data contains: `orgId:secretData`
+     * Only alphanumeric characters, underscores, and hyphens are considered valid in org IDs.
+     *
+     * @param publicKey - The public API key to extract the organization ID from
+     * @returns The organization ID if valid and extractable, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle();
+     * const orgId = toggle.getOrgIdFromPublicKey('public_dGVzdC1vcmc6c2VjcmV0');
+     * console.log(orgId); // 'test-org'
+     * ```
+     */
+    getOrgIdFromPublicKey(publicKey: string): string | undefined;
+    /**
+     * Builds the default Horizon API URL for the given public key.
+     *
+     * If a valid organization ID can be extracted from the public key, returns an
+     * organization-specific URL. Otherwise, returns the default fallback URL.
+     *
+     * @param publicKey - The public API key to build the URL for
+     * @returns Organization-specific URL or default fallback URL
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle();
+     *
+     * // With valid org ID
+     * const orgUrl = toggle.buildDefaultHorizonUrl('public_dGVzdC1vcmc6c2VjcmV0');
+     * console.log(orgUrl); // 'https://test-org.toggle.hyphen.cloud'
+     *
+     * // With invalid key
+     * const defaultUrl = toggle.buildDefaultHorizonUrl('invalid-key');
+     * console.log(defaultUrl); // 'https://toggle.hyphen.cloud'
+     * ```
+     */
+    getDefaultHorizonUrl(publicKey?: string): string;
+    /**
+     * Gets the default Horizon URLs for load balancing and failover.
+     *
+     * If a public key is provided, returns an array with the organization-specific
+     * URL as primary and the default Hyphen URL as fallback. Without a public key,
+     * returns only the default Hyphen URL.
+     *
+     * @param publicKey - Optional public API key to derive organization-specific URL
+     * @returns Array of Horizon URLs for load balancing
+     *
+     * @example
+     * ```typescript
+     * const toggle = new Toggle();
+     *
+     * // Without public key - returns default only
+     * const defaultUrls = toggle.getDefaultHorizonUrls();
+     * // ['https://toggle.hyphen.cloud']
+     *
+     * // With public key - returns org-specific + fallback
+     * const urls = toggle.getDefaultHorizonUrls('public_dGVzdC1vcmc6c2VjcmV0');
+     * // ['https://test-org.toggle.hyphen.cloud', 'https://toggle.hyphen.cloud']
+     * ```
+     */
+    getDefaultHorizonUrls(publicKey?: string): string[];
+    /**
+     * Generates a unique targeting key based on available context.
+     *
+     * @returns A targeting key in the format: `[app]-[env]-[random]` or simplified versions
+     */
+    generateTargetKey(): string;
+    /**
+     * Extracts targeting key from a toggle context with fallback logic.
+     *
+     * @param context - The toggle context to extract targeting key from
+     * @returns The targeting key string
+     */
+    private getTargetingKey;
 }
 
 type HyphenOptions = {
@@ -610,21 +985,21 @@ type HyphenOptions = {
      * @see ToggleOptions
      * @default {Toggle}
      */
-    toggle?: Omit<ToggleOptions, "publicApiKey" | "throwErrors">;
+    toggle?: Omit<ToggleOptions, "publicApiKey">;
     /**
      * Options for the NetInfo service.
      * Excludes apiKey and throwErrors from NetInfoOptions.
      * @see NetInfoOptions
      * @default {NetInfo}
      */
-    netInfo?: Omit<NetInfoOptions, "apiKey" | "throwErrors">;
+    netInfo?: Omit<NetInfoOptions, "apiKey">;
     /**
      * Options for the Link service.
      * Excludes apiKey and throwErrors from LinkOptions.
      * @see LinkOptions
      * @default {Link}
      */
-    link?: Omit<LinkOptions, "apiKey" | "throwErrors">;
+    link?: Omit<LinkOptions, "apiKey">;
 } & HookifiedOptions;
 declare class Hyphen extends Hookified {
     private readonly _netInfo;
@@ -672,18 +1047,6 @@ declare class Hyphen extends Hookified {
      * @param {string | undefined} value - The API key to set.
      */
     set apiKey(value: string | undefined);
-    /**
-     * Get whether to throw errors or not.
-     * If set to true, errors will be thrown instead of logged.
-     * @returns {boolean} Whether to throw errors or not.
-     */
-    get throwErrors(): boolean;
-    /**
-     * Set whether to throw errors or not. If set to true, errors will be thrown instead of logged.
-     * This will update the underlying services as well.
-     * @param {boolean} value - Whether to throw errors or not.
-     */
-    set throwErrors(value: boolean);
 }
 
-export { type EnvOptions, Hyphen, type HyphenOptions, type LoadEnvOptions, Toggle, type ToggleCachingOptions, type ToggleContext, type ToggleGetOptions, ToggleHooks, type ToggleOptions, env, loadEnv };
+export { type EnvOptions, Hyphen, type HyphenOptions, type LoadEnvOptions, Toggle, type ToggleContext, type ToggleEvaluation, ToggleEvents, type ToggleOptions, type ToggleUser, env, loadEnv };