@hyphen/sdk 1.13.0 → 2.0.1

package/dist/index.cjs

@@ -33,7 +33,6 @@ var index_exports = {};
 __export(index_exports, {
   Hyphen: () => Hyphen,
   Toggle: () => Toggle,
-  ToggleHooks: () => ToggleHooks,
   env: () => env,
   loadEnv: () => loadEnv
 });
@@ -124,8 +123,7 @@ var BaseService = class extends import_hookified.Hookified {
       this._throwErrors = options.throwErrors;
     }
     this._net = new import_net.CacheableNet({
-      cache: this._cache,
-      useHttpCache: false
+      cache: this._cache
     });
   }
   get log() {
@@ -191,22 +189,12 @@ var BaseService = class extends import_hookified.Hookified {
     };
   }
   async put(url, data, config2) {
-    const requestInit = {
-      ...config2,
-      method: "PUT",
-      body: typeof data === "string" ? data : JSON.stringify(data),
-      headers: {
-        "Content-Type": "application/json",
-        ...config2?.headers
-      }
-    };
-    const response = await this._net.fetch(url, requestInit);
-    const responseData = await response.json();
+    const response = await this._net.put(url, data, config2);
     return {
-      data: responseData,
-      status: response.status,
-      statusText: response.statusText,
-      headers: response.headers,
+      data: response.data,
+      status: response.response.status,
+      statusText: response.response.statusText,
+      headers: response.response.headers,
       config: config2,
       request: void 0
     };
@@ -221,7 +209,10 @@ var BaseService = class extends import_hookified.Hookified {
     const { data: configData, ...restConfig } = config2 || {};
     let body;
     if (configData) {
-      body = typeof configData === "string" ? configData : JSON.stringify(configData);
+      body = typeof configData === "string" ? (
+        /* c8 ignore next */
+        configData
+      ) : JSON.stringify(configData);
       if (!headers["content-type"] && !headers["Content-Type"]) {
         headers["content-type"] = "application/json";
       }
@@ -777,365 +768,606 @@ var NetInfo = class extends BaseService {
 };
 
 // src/toggle.ts
-var import_node_process4 = __toESM(require("process"), 1);
-var import_openfeature_server_provider = require("@hyphen/openfeature-server-provider");
-var import_server_sdk = require("@openfeature/server-sdk");
-var import_dotenv2 = __toESM(require("dotenv"), 1);
+var import_net2 = require("@cacheable/net");
 var import_hookified2 = require("hookified");
-import_dotenv2.default.config({
-  quiet: true
-});
-var ToggleHooks = /* @__PURE__ */ (function(ToggleHooks2) {
-  ToggleHooks2["beforeGetBoolean"] = "beforeGetBoolean";
-  ToggleHooks2["afterGetBoolean"] = "afterGetBoolean";
-  ToggleHooks2["beforeGetString"] = "beforeGetString";
-  ToggleHooks2["afterGetString"] = "afterGetString";
-  ToggleHooks2["beforeGetNumber"] = "beforeGetNumber";
-  ToggleHooks2["afterGetNumber"] = "afterGetNumber";
-  ToggleHooks2["beforeGetObject"] = "beforeGetObject";
-  ToggleHooks2["afterGetObject"] = "afterGetObject";
-  return ToggleHooks2;
-})({});
 var Toggle = class extends import_hookified2.Hookified {
   static {
     __name(this, "Toggle");
   }
-  _applicationId = import_node_process4.default.env.HYPHEN_APPLICATION_ID;
-  _publicApiKey = import_node_process4.default.env.HYPHEN_PUBLIC_API_KEY;
+  _publicApiKey;
+  _organizationId;
+  _applicationId;
   _environment;
-  _client;
-  _context;
-  _throwErrors = false;
-  _uris;
-  _caching;
-  /*
-  * Create a new Toggle instance. This will create a new client and set the options.
-  * @param {ToggleOptions}
+  _horizonUrls = [];
+  _net = new import_net2.CacheableNet();
+  _defaultContext;
+  _defaultTargetingKey = `${Math.random().toString(36).substring(7)}`;
+  /**
+  * 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) {
     super();
-    this._throwErrors = options?.throwErrors ?? false;
-    this._applicationId = options?.applicationId;
+    if (options?.applicationId) {
+      this._applicationId = options.applicationId;
+    }
+    if (options?.environment) {
+      this._environment = options.environment;
+    } else {
+      this._environment = "development";
+    }
+    if (options?.defaultContext) {
+      this._defaultContext = options.defaultContext;
+    }
     if (options?.publicApiKey) {
-      this.setPublicApiKey(options.publicApiKey);
+      this._publicApiKey = options.publicApiKey;
+      this._organizationId = this.getOrgIdFromPublicKey(this._publicApiKey);
+    }
+    if (options?.horizonUrls) {
+      this._horizonUrls = options.horizonUrls;
+    } else {
+      this._horizonUrls = this.getDefaultHorizonUrls(this._publicApiKey);
+    }
+    if (options?.defaultTargetKey) {
+      this._defaultTargetingKey = options?.defaultTargetKey;
+    } else {
+      if (this._defaultContext) {
+        this._defaultTargetingKey = this.getTargetingKey(this._defaultContext);
+      } else {
+        this._defaultTargetingKey = this.generateTargetKey();
+      }
+    }
+    if (options?.cache) {
+      this._net.cache = options.cache;
     }
-    this._environment = options?.environment ?? import_node_process4.default.env.NODE_ENV ?? "development";
-    this._context = options?.context;
-    this._uris = options?.uris;
-    this._caching = options?.caching;
   }
   /**
-  * Get the application ID
-  * @returns {string | undefined}
+  * Gets the public API key used for authentication.
+  *
+  * @returns The current public API key or undefined if not set
   */
-  get applicationId() {
-    return this._applicationId;
+  get publicApiKey() {
+    return this._publicApiKey;
   }
   /**
-  * Set the application ID
-  * @param {string | undefined} value
+  * 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_"
   */
-  set applicationId(value) {
-    this._applicationId = value;
+  set publicApiKey(value) {
+    this.setPublicKey(value);
   }
   /**
-  * Get the public API key
-  * @returns {string}
+  * Gets the default context used for toggle evaluations.
+  *
+  * @returns The current default ToggleContext
   */
-  get publicApiKey() {
-    return this._publicApiKey;
+  get defaultContext() {
+    return this._defaultContext;
   }
   /**
-  * Set the public API key
-  * @param {string} value
+  * Sets the default context used for toggle evaluations.
+  *
+  * @param value - The ToggleContext to use as default
   */
-  set publicApiKey(value) {
-    if (!value) {
-      this._publicApiKey = void 0;
-      this._client = void 0;
-      return;
-    }
-    this.setPublicApiKey(value);
+  set defaultContext(value) {
+    this._defaultContext = value;
   }
   /**
-  * Get the environment
-  * @returns {string}
+  * Gets the organization ID extracted from the public API key.
+  *
+  * @returns The organization ID string or undefined if not available
   */
-  get environment() {
-    return this._environment;
+  get organizationId() {
+    return this._organizationId;
   }
   /**
-  * Set the environment
-  * @param {string} value
+  * 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
   */
-  set environment(value) {
-    this._environment = value;
+  get horizonUrls() {
+    return this._horizonUrls;
   }
   /**
-  * Get the throwErrors. If true, errors will be thrown in addition to being emitted.
-  * @returns {boolean}
+  * 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'
+  * ];
+  * ```
   */
-  get throwErrors() {
-    return this._throwErrors;
+  set horizonUrls(value) {
+    this._horizonUrls = value;
   }
   /**
-  * Set the throwErrors. If true, errors will be thrown in addition to being emitted.
-  * @param {boolean} value
+  * Gets the application ID used for toggle context.
+  *
+  * @returns The current application ID or undefined if not set
   */
-  set throwErrors(value) {
-    this._throwErrors = value;
+  get applicationId() {
+    return this._applicationId;
   }
   /**
-  * Get the current context. This is the default context used. You can override this at the get function level.
-  * @returns {ToggleContext}
+  * Sets the application ID used for toggle context.
+  *
+  * @param value - The application ID string or undefined to clear
   */
-  get context() {
-    return this._context;
+  set applicationId(value) {
+    this._applicationId = value;
   }
   /**
-  * Set the context. This is the default context used. You can override this at the get function level.
-  * @param {ToggleContext} value
+  * Gets the environment used for toggle context.
+  *
+  * @returns The current environment (defaults to 'development')
   */
-  set context(value) {
-    this._context = value;
+  get environment() {
+    return this._environment;
   }
   /**
-  * 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 environment used for toggle context.
+  *
+  * @param value - The environment string or undefined to clear
   */
-  get uris() {
-    return this._uris;
+  set environment(value) {
+    this._environment = value;
   }
   /**
-  * 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 targeting key used for toggle evaluations.
+  *
+  * @returns The current default targeting key or undefined if not set
   */
-  set uris(value) {
-    this._uris = value;
+  get defaultTargetingKey() {
+    return this._defaultTargetingKey;
   }
   /**
-  * Get the caching options.
-  * @returns {ToggleCachingOptions | undefined}
+  * Sets the default targeting key used for toggle evaluations.
+  *
+  * @param value - The targeting key string or undefined to clear
   */
-  get caching() {
-    return this._caching;
+  set defaultTargetingKey(value) {
+    this._defaultTargetingKey = value;
   }
   /**
-  * Set the caching options.
-  * @param {ToggleCachingOptions | undefined} value
+  * Gets the Cacheable instance used for caching fetch operations.
+  *
+  * @returns The current Cacheable instance
   */
-  set caching(value) {
-    this._caching = value;
+  get cache() {
+    return this._net.cache;
   }
   /**
-  * 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
+  * Sets the Cacheable instance for caching fetch operations.
+  *
+  * @param cache - The Cacheable instance to use for caching
   */
-  setPublicApiKey(key) {
-    if (!key.startsWith("public_")) {
-      this.emit("error", new Error("Public API key should start with public_"));
-      if (import_node_process4.default.env.NODE_ENV !== "production") {
-        console.error("Public API key should start with public_");
+  set cache(cache) {
+    this._net.cache = cache;
+  }
+  /**
+  * 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' }
+  * });
+  * ```
+  */
+  async get(toggleKey, defaultValue, options) {
+    try {
+      const context = {
+        application: this._applicationId ?? "",
+        environment: this._environment ?? "development"
+      };
+      if (options?.context) {
+        context.targetingKey = options?.context.targetingKey;
+        context.ipAddress = options?.context.ipAddress;
+        context.user = options?.context.user;
+        context.customAttributes = options?.context.customAttributes;
+      } else {
+        context.targetingKey = this._defaultContext?.targetingKey;
+        context.ipAddress = this._defaultContext?.ipAddress;
+        context.user = this._defaultContext?.user;
+        context.customAttributes = this._defaultContext?.customAttributes;
       }
-      return;
+      const fetchOptions = {
+        headers: {}
+      };
+      if (!context.targetingKey) {
+        context.targetingKey = this.getTargetingKey(context);
+      }
+      if (this._publicApiKey) {
+        fetchOptions.headers["x-api-key"] = this._publicApiKey;
+      } else {
+        throw new Error("You must set the publicApiKey");
+      }
+      if (context.application === "") {
+        throw new Error("You must set the applicationId");
+      }
+      const result = await this.fetch("/toggle/evaluate", context, fetchOptions);
+      if (result?.toggles) {
+        return result.toggles[toggleKey].value;
+      }
+    } catch (error) {
+      this.emit("error", error);
     }
-    this._publicApiKey = key;
-    this._client = void 0;
+    return defaultValue;
   }
   /**
-  * Set the context. This is the default context used. You can override this at the get function level.
-  * @param {ToggleContext} context
+  * 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
+  * ```
   */
-  setContext(context) {
-    this._context = context;
-    this._client = void 0;
+  async getBoolean(toggleKey, defaultValue, options) {
+    return this.get(toggleKey, defaultValue, options);
   }
   /**
-  * 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>}
+  * 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'
+  * ```
   */
-  async getClient() {
-    if (!this._client) {
-      if (this._applicationId === void 0 || this._applicationId.length === 0) {
-        const errorMessage = "Application ID is not set. You must set it before using the client or have the HYPHEN_APPLICATION_ID environment variable set.";
-        this.emit("error", new Error(errorMessage));
-        if (this._throwErrors) {
-          throw new Error(errorMessage);
-        }
-      }
-      const options = {
-        application: this._applicationId,
-        environment: this._environment,
-        horizonUrls: this._uris,
-        cache: this._caching
-      };
-      if (this._publicApiKey && this._publicApiKey.length > 0) {
-        await import_server_sdk.OpenFeature.setProviderAndWait(new import_openfeature_server_provider.HyphenProvider(this._publicApiKey, options));
+  async getString(toggleKey, defaultValue, options) {
+    return this.get(toggleKey, defaultValue, options);
+  }
+  /**
+  * 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' }
+  * ```
+  */
+  async getObject(toggleKey, defaultValue, options) {
+    return this.get(toggleKey, defaultValue, options);
+  }
+  /**
+  * 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
+  * ```
+  */
+  async getNumber(toggleKey, defaultValue, options) {
+    return this.get(toggleKey, defaultValue, options);
+  }
+  /**
+  * 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
+  * ```
+  */
+  async fetch(path2, payload, options) {
+    if (this._horizonUrls.length === 0) {
+      throw new Error("No horizon URLs configured. Set horizonUrls or provide a valid publicApiKey.");
+    }
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (options?.headers) {
+      if (options.headers instanceof Headers) {
+        options.headers.forEach((value, key) => {
+          headers[key] = value;
+        });
+      } else if (Array.isArray(options.headers)) {
+        options.headers.forEach(([key, value]) => {
+          headers[key] = value;
+        });
       } else {
-        this.emit("error", new Error("Public API key is not set. You must set it before using the client or have the HYPHEN_PUBLIC_API_KEY environment variable set."));
-        if (this._throwErrors) {
-          throw new Error("Public API key is not set");
+        Object.assign(headers, options.headers);
+      }
+    }
+    if (this._publicApiKey) {
+      headers["x-api-key"] = this._publicApiKey;
+    }
+    const fetchOptions = {
+      method: "POST",
+      ...options,
+      headers,
+      body: payload ? JSON.stringify(payload) : options?.body
+    };
+    const errors = [];
+    for (const baseUrl of this._horizonUrls) {
+      try {
+        const url = `${baseUrl.replace(/\/$/, "")}${path2.startsWith("/") ? path2 : `/${path2}`}`;
+        const response = await this._net.fetch(url, fetchOptions);
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data;
+      } catch (error) {
+        const fetchError = error instanceof Error ? error : new Error("Unknown fetch error");
+        const statusMatch = fetchError.message.match(/status (\d{3})/);
+        if (statusMatch) {
+          const status = statusMatch[1];
+          errors.push(new Error(`HTTP ${status}: ${fetchError.message}`));
+        } else {
+          errors.push(fetchError);
         }
       }
-      this._client = import_server_sdk.OpenFeature.getClient(this._context);
     }
-    return this._client;
+    throw new Error(`All horizon URLs failed. Last errors: ${errors.map((e) => e.message).join(", ")}`);
   }
   /**
-  * 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>}
+  * 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
+  * ```
   */
-  async get(key, defaultValue, options) {
-    switch (typeof defaultValue) {
-      case "boolean": {
-        return this.getBoolean(key, defaultValue, options);
-      }
-      case "string": {
-        return this.getString(key, defaultValue, options);
-      }
-      case "number": {
-        return this.getNumber(key, defaultValue, options);
-      }
-      default: {
-        return this.getObject(key, defaultValue, options);
-      }
+  setPublicKey(key) {
+    if (key !== void 0 && !key.startsWith("public_")) {
+      throw new Error("Public API key must start with 'public_'");
     }
+    this._publicApiKey = key;
   }
   /**
-  * 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
+  * 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'
+  * ```
   */
-  async getBoolean(key, defaultValue, options) {
+  getOrgIdFromPublicKey(publicKey) {
     try {
-      const data = {
-        key,
-        defaultValue,
-        options
-      };
-      await this.hook("beforeGetBoolean", data);
-      const client = await this.getClient();
-      const result = await client.getBooleanValue(data.key, data.defaultValue, data.options?.context);
-      const resultData = {
-        key,
-        defaultValue,
-        options,
-        result
-      };
-      await this.hook("afterGetBoolean", resultData);
-      return resultData.result;
-    } catch (error) {
-      this.emit("error", error);
-      if (this._throwErrors) {
-        throw error;
-      }
+      const keyWithoutPrefix = publicKey.replace(/^public_/, "");
+      const decoded = globalThis.atob ? globalThis.atob(keyWithoutPrefix) : Buffer.from(keyWithoutPrefix, "base64").toString();
+      const [orgId] = decoded.split(":");
+      const isValidOrgId = /^[a-zA-Z0-9_-]+$/.test(orgId);
+      return isValidOrgId ? orgId : void 0;
+    } catch {
+      return void 0;
     }
-    return defaultValue;
   }
   /**
-  * 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
+  * 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'
+  * ```
   */
-  async getString(key, defaultValue, options) {
-    try {
-      const data = {
-        key,
-        defaultValue,
-        options
-      };
-      await this.hook("beforeGetString", data);
-      const client = await this.getClient();
-      const result = await client.getStringValue(data.key, data.defaultValue, data.options?.context);
-      const resultData = {
-        key,
-        defaultValue,
-        options,
-        result
-      };
-      await this.hook("afterGetString", resultData);
-      return resultData.result;
-    } catch (error) {
-      this.emit("error", error);
-      if (this._throwErrors) {
-        throw error;
-      }
+  getDefaultHorizonUrl(publicKey) {
+    if (publicKey) {
+      const orgId = this.getOrgIdFromPublicKey(publicKey);
+      return orgId ? `https://${orgId}.toggle.hyphen.cloud` : "https://toggle.hyphen.cloud";
     }
-    return defaultValue;
+    return "https://toggle.hyphen.cloud";
   }
-  async getNumber(key, defaultValue, options) {
-    try {
-      const data = {
-        key,
-        defaultValue,
-        options
-      };
-      await this.hook("beforeGetNumber", data);
-      const client = await this.getClient();
-      const result = await client.getNumberValue(data.key, data.defaultValue, data.options?.context);
-      const resultData = {
-        key,
-        defaultValue,
-        options,
-        result
-      };
-      await this.hook("afterGetNumber", resultData);
-      return resultData.result;
-    } catch (error) {
-      this.emit("error", error);
-      if (this._throwErrors) {
-        throw error;
+  /**
+  * 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) {
+    let result = [
+      this.getDefaultHorizonUrl()
+    ];
+    if (publicKey) {
+      const defaultUrl = result[0];
+      const orgUrl = this.getDefaultHorizonUrl(publicKey);
+      result = [];
+      if (orgUrl !== defaultUrl) {
+        result.push(orgUrl);
       }
+      result.push(defaultUrl);
     }
-    return defaultValue;
+    return result;
   }
   /**
-  * 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
+  * Generates a unique targeting key based on available context.
+  *
+  * @returns A targeting key in the format: `[app]-[env]-[random]` or simplified versions
   */
-  async getObject(key, defaultValue, options) {
-    try {
-      const data = {
-        key,
-        defaultValue,
-        options
-      };
-      await this.hook("beforeGetObject", data);
-      const client = await this.getClient();
-      const result = await client.getObjectValue(key, defaultValue, data.options?.context);
-      const resultData = {
-        key,
-        defaultValue,
-        options,
-        result
-      };
-      await this.hook("afterGetObject", resultData);
-      return resultData.result;
-    } catch (error) {
-      this.emit("error", error);
-      if (this._throwErrors) {
-        throw error;
-      }
+  generateTargetKey() {
+    const randomSuffix = Math.random().toString(36).substring(7);
+    const app = this._applicationId || "";
+    const env2 = this._environment || "";
+    const components = [
+      app,
+      env2,
+      randomSuffix
+    ].filter(Boolean);
+    return components.join("-");
+  }
+  /**
+  * 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
+  */
+  getTargetingKey(context) {
+    if (context.targetingKey) {
+      return context.targetingKey;
     }
-    return defaultValue;
+    if (context.user) {
+      return context.user.id;
+    }
+    return this._defaultTargetingKey;
   }
 };
 
@@ -1163,11 +1395,6 @@ var Hyphen = class extends import_hookified3.Hookified {
       netInfoOptions.apiKey = options.apiKey;
       linkOptions.apiKey = options.apiKey;
     }
-    if (options?.throwErrors !== void 0) {
-      toggleOptions.throwErrors = options.throwErrors;
-      netInfoOptions.throwErrors = options.throwErrors;
-      linkOptions.throwErrors = options.throwErrors;
-    }
     this._netInfo = new NetInfo(netInfoOptions);
     this._netInfo.on("error", (message, ...args) => this.emit("error", message, ...args));
     this._netInfo.on("info", (message, ...args) => this.emit("info", message, ...args));
@@ -1237,30 +1464,11 @@ var Hyphen = class extends import_hookified3.Hookified {
     this._netInfo.apiKey = value;
     this._link.apiKey = value;
   }
-  /**
-  * 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() {
-    return this._netInfo.throwErrors && this._toggle.throwErrors && this._link.throwErrors;
-  }
-  /**
-  * 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) {
-    this._netInfo.throwErrors = value;
-    this._toggle.throwErrors = value;
-    this._link.throwErrors = value;
-  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Hyphen,
   Toggle,
-  ToggleHooks,
   env,
   loadEnv
 });