@hyphen/sdk 1.1.0 → 1.3.0

package/README.md

@@ -10,7 +10,6 @@
 The Hyphen Node.js SDK is a JavaScript library that allows developers to easily integrate Hyphen's feature flagging and experimentation capabilities into their Node.js applications. With this SDK, you can manage feature flags more effectively, enabling you to control the rollout of new features and conduct A/B testing with ease.
 
 # Table of Contents
-- [Hyphen Node.js SDK](#hyphen-nodejs-sdk)
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
 - [Toggle](#toggle)
@@ -18,6 +17,7 @@ The Hyphen Node.js SDK is a JavaScript library that allows developers to easily
 	- [Toggle API](#toggle-api)
 	- [Toggle Hooks](#toggle-hooks)
 	- [Toggle Error Handling](#toggle-error-handling)
+	- [Toggle Caching](#toggle-caching)
 	- [Toggle Self-Hosted](#toggle-self-hosted)
 - [Contributing](#contributing)
 - [Testing Your Changes](#testing-your-changes)
@@ -168,32 +168,32 @@ console.log('Boolean toggle value:', result); // true
 | *applicationId* | `string` | The application ID for your Hyphen project. You can find this in the Hyphen dashboard. |
 | *environment?* | `string` | The environment for your Hyphen project such as `production`. Default uses `process.env.NODE_ENV`  |
 | *context?* | `ToggleContext` | The context object that contains the user and custom attributes. This is optional. |
-| *cache?* | `{ ttl: number}` | Whether to use the cache or not. |
+| *caching?* | `{ ttl: number, generateCacheKeyFn: (context?: ToggleContext) => string}` | Whether to use the cache or not and a function to set the key. The `ttl` is in seconds |
 
 ## Toggle API
 
 | Method | Parameters | Description |
 |----------------|----------------|----------------|
 | *setContext* | `context: ToggleContext` | Set the context for the toggle. This is optional. |
-| *get<Type>* | `key: string, defaultValue: T, options?: ToggleRequestOptions` | Get the value of a toggle. This is a generic method that can be used to get any type from toggle. |
-| *getBoolean* | `key: string, defaultValue: boolean, options?: ToggleRequestOptions` | Get the value of a boolean toggle. |
-| *getNumber* | `key: string, defaultValue: number, options?: ToggleRequestOptions` | Get the value of a number toggle. |
-| *getString* | `key: string, defaultValue: string, options?: ToggleRequestOptions` | Get the value of a string toggle. |
-| *getObject<Type>* | `key: string, defaultValue: any, options?: ToggleRequestOptions` | Get the value of a object toggle. |
+| *get<Type>* | `key: string, defaultValue: T, options?: ToggleGetOptions` | Get the value of a toggle. This is a generic method that can be used to get any type from toggle. |
+| *getBoolean* | `key: string, defaultValue: boolean, options?: ToggleGetOptions` | Get the value of a boolean toggle. |
+| *getNumber* | `key: string, defaultValue: number, options?: ToggleGetOptions` | Get the value of a number toggle. |
+| *getString* | `key: string, defaultValue: string, options?: ToggleGetOptions` | Get the value of a string toggle. |
+| *getObject<Type>* | `key: string, defaultValue: any, options?: ToggleGetOptions` | Get the value of a object toggle. |
 
 ## Toggle Hooks
 
 The following hooks are available for Toggle:
 | Hook | object | Description |
 |----------------|----------------|----------------|
-| *beforeGetBoolean* | `{ key: string, defaultValue:boolean, options?: ToggleRequestOptions }` | Called before the boolean toggle is fetched. |
-| *afterGetBoolean* | `{ key: string, defaultValue:boolean, options?: ToggleRequestOptions, result: boolean }` | Called after the boolean toggle is fetched. |
-| *beforeGetNumber* | `{ key: string, defaultValue:number, options?: ToggleRequestOptions }` | Called before the number toggle is fetched. |
-| *afterGetNumber* | `{ key: string, defaultValue:number, options?: ToggleRequestOptions, result: number }` | Called after the number toggle is fetched. |
-| *beforeGetString* | `{ key: string, defaultValue:string, options?: ToggleRequestOptions }` | Called before the string toggle is fetched. |
-| *afterGetString* | `{ key: string, defaultValue:string, options?: ToggleRequestOptions, result: string }` | Called after the string toggle is fetched. |
-| *beforeGetObject* | `{ key: string, defaultValue:any, options?: ToggleRequestOptions }` | Called before the object toggle is fetched. |
-| *afterGetObject* | `{ key: string, defaultValue:any, options?: ToggleRequestOptions, result: any }` | Called after the object toggle is fetched. |
+| *beforeGetBoolean* | `{ key: string, defaultValue:boolean, options?: ToggleGetOptions }` | Called before the boolean toggle is fetched. |
+| *afterGetBoolean* | `{ key: string, defaultValue:boolean, options?: ToggleGetOptions, result: boolean }` | Called after the boolean toggle is fetched. |
+| *beforeGetNumber* | `{ key: string, defaultValue:number, options?: ToggleGetOptions }` | Called before the number toggle is fetched. |
+| *afterGetNumber* | `{ key: string, defaultValue:number, options?: ToggleGetOptions, result: number }` | Called after the number toggle is fetched. |
+| *beforeGetString* | `{ key: string, defaultValue:string, options?: ToggleGetOptions }` | Called before the string toggle is fetched. |
+| *afterGetString* | `{ key: string, defaultValue:string, options?: ToggleGetOptions, result: string }` | Called after the string toggle is fetched. |
+| *beforeGetObject* | `{ key: string, defaultValue:any, options?: ToggleGetOptions }` | Called before the object toggle is fetched. |
+| *afterGetObject* | `{ key: string, defaultValue:any, options?: ToggleGetOptions, result: any }` | Called after the object toggle is fetched. |
 
 You can use the hooks to modify the request or the response. For example, you can use the `beforeGetBoolean` hook to log the request before it is sent to the server.
 
@@ -312,6 +312,89 @@ try {
 }
 ```
 
+## Toggle Caching
+The SDK supports caching of toggle values to improve performance and reduce the number of requests made to the server. You can enable caching by providing a `caching` option in the constructor.
+
+```javascript
+import { Toggle, ToggleContext } from '@hyphen/sdk';
+
+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',
+		},
+	},
+};
+
+const toggleOptions = {
+  publicApiKey: 'your_public_api_key',
+  applicationId: 'your_application_id',
+  context: context,
+  uris: [
+	'https://your-self-hosted-horizon-url',
+  ],
+  caching: {
+	ttl: 60, // Cache for 60 seconds
+};
+
+const toggle = new Toggle(toggleOptions);
+
+const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
+console.log('Boolean toggle value:', result); // true
+```
+
+If you want to use a custom cache key generation function, you can provide a `generateCacheKeyFn` function in the `caching` option:
+
+```javascript
+import { Toggle, ToggleContext } from '@hyphen/sdk';
+
+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',
+		},
+	},
+};
+
+const toggleOptions = {
+  publicApiKey: 'your_public_api_key',
+  applicationId: 'your_application_id',
+  context: context,
+  uris: [
+	'https://your-self-hosted-horizon-url',
+  ],
+  caching: {
+	ttl: 60, // Cache for 60 seconds
+	generateCacheKeyFn: (context) => {
+		return `toggle-${context?.targetingKey || 'default'}-hyphen-sdk-boolean`;
+	},
+  },
+};
+
+const toggle = new Toggle(toggleOptions);
+
+const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
+console.log('Boolean toggle value:', result); // true
+```
+
 ## Toggle Self-Hosted
 
 Toggle uses [Horizon](https://hyphen.ai/horizon) to fetch the feature flags. If you are using a self-hosted version of Hyphen you can use the `uris` option in the constructor to set the url of your self-hosted version:

package/dist/index.cjs

@@ -57,73 +57,178 @@ var Toggle = class extends import_hookified.Hookified {
     __name(this, "Toggle");
   }
   _applicationId;
-  _publicKey;
+  _publicApiKey = "";
   _environment;
   _client;
   _context;
   _throwErrors = false;
   _uris;
+  _caching;
+  /*
+   * Create a new Toggle instance. This will create a new client and set the options.
+   * @param {ToggleOptions}
+  */
   constructor(options) {
     super();
     this._applicationId = options.applicationId;
-    this._publicKey = options.publicKey;
+    this.setPublicApiKey(options.publicApiKey);
     this._environment = options.environment ?? import_node_process.default.env.NODE_ENV ?? "development";
     this._context = options.context;
     this._throwErrors = options.throwErrors ?? false;
     this._uris = options.uris;
+    this._caching = options.caching;
   }
+  /**
+  * Get the application ID
+  * @returns {string}
+  */
   get applicationId() {
     return this._applicationId;
   }
+  /**
+  * Set the application ID
+  * @param {string} value
+  */
   set applicationId(value) {
     this._applicationId = value;
   }
-  get publicKey() {
-    return this._publicKey;
+  /**
+  * Get the public API key
+  * @returns {string}
+  */
+  get publicApiKey() {
+    return this._publicApiKey;
   }
-  set publicKey(value) {
-    this._publicKey = value;
+  /**
+  * Set the public API key
+  * @param {string} value
+  */
+  set publicApiKey(value) {
+    this.setPublicApiKey(value);
   }
+  /**
+  * Get the environment
+  * @returns {string}
+  */
   get environment() {
     return this._environment;
   }
+  /**
+  * Set the environment
+  * @param {string} value
+  */
   set environment(value) {
     this._environment = value;
   }
+  /**
+  * Get the throwErrors. If true, errors will be thrown in addition to being emitted.
+  * @returns {boolean}
+  */
   get throwErrors() {
     return this._throwErrors;
   }
+  /**
+  * Set the throwErrors. If true, errors will be thrown in addition to being emitted.
+  * @param {boolean} value
+  */
   set throwErrors(value) {
     this._throwErrors = value;
   }
+  /**
+  * Get the current context. This is the default context used. You can override this at the get function level.
+  * @returns {ToggleContext}
+  */
   get context() {
     return this._context;
   }
+  /**
+  * Set the context. This is the default context used. You can override this at the get function level.
+  * @param {ToggleContext} value
+  */
   set context(value) {
     this._context = value;
   }
+  /**
+  * 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>}
+  */
   get uris() {
     return this._uris;
   }
+  /**
+  * 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
+  */
   set uris(value) {
     this._uris = value;
   }
+  /**
+  * Get the caching options.
+  * @returns {ToggleCachingOptions | undefined}
+  */
+  get caching() {
+    return this._caching;
+  }
+  /**
+  * Set the caching options.
+  * @param {ToggleCachingOptions | undefined} value
+  */
+  set caching(value) {
+    this._caching = value;
+  }
+  /**
+  * 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
+  */
+  setPublicApiKey(key) {
+    if (!key.startsWith("public_")) {
+      this.emit("error", new Error("Public API key should start with public_"));
+      if (import_node_process.default.env.NODE_ENV !== "production") {
+        console.error("Public API key should start with public_");
+      }
+      return;
+    }
+    this._publicApiKey = key;
+    this._client = void 0;
+  }
+  /**
+  * Set the context. This is the default context used. You can override this at the get function level.
+  * @param {ToggleContext} context
+  */
   setContext(context) {
     this._context = context;
     this._client = void 0;
   }
+  /**
+  * 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>}
+  */
   async getClient() {
     if (!this._client) {
       const options = {
         application: this._applicationId,
         environment: this._environment,
-        horizonUrls: this._uris
+        horizonUrls: this._uris,
+        cache: this._caching
       };
-      await import_server_sdk.OpenFeature.setProviderAndWait(new import_openfeature_server_provider.HyphenProvider(this._publicKey, options));
+      await import_server_sdk.OpenFeature.setProviderAndWait(new import_openfeature_server_provider.HyphenProvider(this._publicApiKey, options));
       this._client = import_server_sdk.OpenFeature.getClient(this._context);
     }
     return this._client;
   }
+  /**
+  * 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>}
+  */
   async get(key, defaultValue, options) {
     switch (typeof defaultValue) {
       case "boolean": {
@@ -140,6 +245,14 @@ var Toggle = class extends import_hookified.Hookified {
       }
     }
   }
+  /**
+  * 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
+  */
   async getBoolean(key, defaultValue, options) {
     try {
       const data = {
@@ -166,6 +279,13 @@ var Toggle = class extends import_hookified.Hookified {
     }
     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
+  */
   async getString(key, defaultValue, options) {
     try {
       const data = {
@@ -218,6 +338,14 @@ var Toggle = class extends import_hookified.Hookified {
     }
     return defaultValue;
   }
+  /**
+  * 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
+  */
   async getObject(key, defaultValue, options) {
     try {
       const data = {

package/dist/index.d.cts

@@ -12,6 +12,10 @@ declare enum ToggleHooks {
     beforeGetObject = "beforeGetObject",
     afterGetObject = "afterGetObject"
 }
+type ToggleCachingOptions = {
+    ttl?: number;
+    generateCacheKeyFn?: (context?: ToggleContext) => string;
+};
 type ToggleOptions = {
     /**
      * Your application name
@@ -19,10 +23,10 @@ type ToggleOptions = {
      */
     applicationId: string;
     /**
-     * Your Hyphen API key
+     * Your Hyphen Public API key
      * @type {string}
      */
-    publicKey: string;
+    publicApiKey: string;
     /**
      * Your environment name such as development, production. Default is what is set at NODE_ENV
      * @type {string}
@@ -34,13 +38,11 @@ type ToggleOptions = {
      * @type {ToggleContext}
      */
     context?: ToggleContext;
-    caching?: {
-        /**
-         * The time in seconds to cache the feature flag values
-         * @type {number} - this is in milliseconds
-         */
-        ttl?: number;
-    };
+    /**
+     * Cache options to use for the request
+     * @type {ToggleCachingOptions}
+     */
+    caching?: ToggleCachingOptions;
     /**
      * Throw errors in addition to emitting them
      * @type {boolean}
@@ -55,37 +57,149 @@ type ToggleOptions = {
      */
     uris?: string[];
 };
-type ToggleRequestOptions = {
+type ToggleGetOptions = {
+    /**
+     * The context to use for evaluating feature flags
+     * @type {ToggleContext}
+     */
     context?: ToggleContext;
 };
 declare class Toggle extends Hookified {
     private _applicationId;
-    private _publicKey;
+    private _publicApiKey;
     private _environment;
     private _client;
     private _context;
     private _throwErrors;
-    private _uris?;
+    private _uris;
+    private _caching;
     constructor(options: ToggleOptions);
+    /**
+     * Get the application ID
+     * @returns {string}
+     */
     get applicationId(): string;
+    /**
+     * Set the application ID
+     * @param {string} value
+     */
     set applicationId(value: string);
-    get publicKey(): string;
-    set publicKey(value: string);
+    /**
+     * Get the public API key
+     * @returns {string}
+     */
+    get publicApiKey(): string;
+    /**
+     * Set the public API key
+     * @param {string} value
+     */
+    set publicApiKey(value: string);
+    /**
+     * Get the environment
+     * @returns {string}
+     */
     get environment(): string;
+    /**
+     * Set the environment
+     * @param {string} value
+     */
     set environment(value: string);
+    /**
+     * Get the throwErrors. If true, errors will be thrown in addition to being emitted.
+     * @returns {boolean}
+     */
     get throwErrors(): boolean;
+    /**
+     * Set the throwErrors. If true, errors will be thrown in addition to being emitted.
+     * @param {boolean} value
+     */
     set throwErrors(value: boolean);
+    /**
+     * Get the current context. This is the default context used. You can override this at the get function level.
+     * @returns {ToggleContext}
+     */
     get context(): ToggleContext | undefined;
+    /**
+     * Set the context. This is the default context used. You can override this at the get function level.
+     * @param {ToggleContext} value
+     */
     set context(value: ToggleContext | 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>}
+     */
     get uris(): 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
+     */
     set uris(value: string[] | undefined);
+    /**
+     * Get the caching options.
+     * @returns {ToggleCachingOptions | undefined}
+     */
+    get caching(): ToggleCachingOptions | undefined;
+    /**
+     * Set the caching options.
+     * @param {ToggleCachingOptions | undefined} value
+     */
+    set caching(value: ToggleCachingOptions | 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
+     */
+    setPublicApiKey(key: string): void;
+    /**
+     * Set the context. This is the default context used. You can override this at the get function level.
+     * @param {ToggleContext} context
+     */
     setContext(context: ToggleContext): void;
+    /**
+     * 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>}
+     */
     getClient(): Promise<Client>;
-    get<T>(key: string, defaultValue: T, options?: ToggleRequestOptions): Promise<T>;
-    getBoolean(key: string, defaultValue: boolean, options?: ToggleRequestOptions): Promise<boolean>;
-    getString(key: string, defaultValue: string, options?: ToggleRequestOptions): Promise<string>;
-    getNumber(key: string, defaultValue: number, options?: ToggleRequestOptions): Promise<number>;
-    getObject<T>(key: string, defaultValue: T, options?: ToggleRequestOptions): Promise<T>;
+    /**
+     * 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>}
+     */
+    get<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
+    /**
+     * 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
+     */
+    getBoolean(key: string, defaultValue: boolean, options?: ToggleGetOptions): Promise<boolean>;
+    /**
+     * 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
+     */
+    getString(key: string, defaultValue: string, options?: ToggleGetOptions): Promise<string>;
+    getNumber(key: string, defaultValue: number, options?: ToggleGetOptions): Promise<number>;
+    /**
+     * 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
+     */
+    getObject<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
 }
 
-export { Toggle, type ToggleContext, ToggleHooks, type ToggleOptions, type ToggleRequestOptions };
+export { Toggle, type ToggleCachingOptions, type ToggleContext, type ToggleGetOptions, ToggleHooks, type ToggleOptions };

package/dist/index.d.ts

@@ -12,6 +12,10 @@ declare enum ToggleHooks {
     beforeGetObject = "beforeGetObject",
     afterGetObject = "afterGetObject"
 }
+type ToggleCachingOptions = {
+    ttl?: number;
+    generateCacheKeyFn?: (context?: ToggleContext) => string;
+};
 type ToggleOptions = {
     /**
      * Your application name
@@ -19,10 +23,10 @@ type ToggleOptions = {
      */
     applicationId: string;
     /**
-     * Your Hyphen API key
+     * Your Hyphen Public API key
      * @type {string}
      */
-    publicKey: string;
+    publicApiKey: string;
     /**
      * Your environment name such as development, production. Default is what is set at NODE_ENV
      * @type {string}
@@ -34,13 +38,11 @@ type ToggleOptions = {
      * @type {ToggleContext}
      */
     context?: ToggleContext;
-    caching?: {
-        /**
-         * The time in seconds to cache the feature flag values
-         * @type {number} - this is in milliseconds
-         */
-        ttl?: number;
-    };
+    /**
+     * Cache options to use for the request
+     * @type {ToggleCachingOptions}
+     */
+    caching?: ToggleCachingOptions;
     /**
      * Throw errors in addition to emitting them
      * @type {boolean}
@@ -55,37 +57,149 @@ type ToggleOptions = {
      */
     uris?: string[];
 };
-type ToggleRequestOptions = {
+type ToggleGetOptions = {
+    /**
+     * The context to use for evaluating feature flags
+     * @type {ToggleContext}
+     */
     context?: ToggleContext;
 };
 declare class Toggle extends Hookified {
     private _applicationId;
-    private _publicKey;
+    private _publicApiKey;
     private _environment;
     private _client;
     private _context;
     private _throwErrors;
-    private _uris?;
+    private _uris;
+    private _caching;
     constructor(options: ToggleOptions);
+    /**
+     * Get the application ID
+     * @returns {string}
+     */
     get applicationId(): string;
+    /**
+     * Set the application ID
+     * @param {string} value
+     */
     set applicationId(value: string);
-    get publicKey(): string;
-    set publicKey(value: string);
+    /**
+     * Get the public API key
+     * @returns {string}
+     */
+    get publicApiKey(): string;
+    /**
+     * Set the public API key
+     * @param {string} value
+     */
+    set publicApiKey(value: string);
+    /**
+     * Get the environment
+     * @returns {string}
+     */
     get environment(): string;
+    /**
+     * Set the environment
+     * @param {string} value
+     */
     set environment(value: string);
+    /**
+     * Get the throwErrors. If true, errors will be thrown in addition to being emitted.
+     * @returns {boolean}
+     */
     get throwErrors(): boolean;
+    /**
+     * Set the throwErrors. If true, errors will be thrown in addition to being emitted.
+     * @param {boolean} value
+     */
     set throwErrors(value: boolean);
+    /**
+     * Get the current context. This is the default context used. You can override this at the get function level.
+     * @returns {ToggleContext}
+     */
     get context(): ToggleContext | undefined;
+    /**
+     * Set the context. This is the default context used. You can override this at the get function level.
+     * @param {ToggleContext} value
+     */
     set context(value: ToggleContext | 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>}
+     */
     get uris(): 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
+     */
     set uris(value: string[] | undefined);
+    /**
+     * Get the caching options.
+     * @returns {ToggleCachingOptions | undefined}
+     */
+    get caching(): ToggleCachingOptions | undefined;
+    /**
+     * Set the caching options.
+     * @param {ToggleCachingOptions | undefined} value
+     */
+    set caching(value: ToggleCachingOptions | 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
+     */
+    setPublicApiKey(key: string): void;
+    /**
+     * Set the context. This is the default context used. You can override this at the get function level.
+     * @param {ToggleContext} context
+     */
     setContext(context: ToggleContext): void;
+    /**
+     * 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>}
+     */
     getClient(): Promise<Client>;
-    get<T>(key: string, defaultValue: T, options?: ToggleRequestOptions): Promise<T>;
-    getBoolean(key: string, defaultValue: boolean, options?: ToggleRequestOptions): Promise<boolean>;
-    getString(key: string, defaultValue: string, options?: ToggleRequestOptions): Promise<string>;
-    getNumber(key: string, defaultValue: number, options?: ToggleRequestOptions): Promise<number>;
-    getObject<T>(key: string, defaultValue: T, options?: ToggleRequestOptions): Promise<T>;
+    /**
+     * 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>}
+     */
+    get<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
+    /**
+     * 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
+     */
+    getBoolean(key: string, defaultValue: boolean, options?: ToggleGetOptions): Promise<boolean>;
+    /**
+     * 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
+     */
+    getString(key: string, defaultValue: string, options?: ToggleGetOptions): Promise<string>;
+    getNumber(key: string, defaultValue: number, options?: ToggleGetOptions): Promise<number>;
+    /**
+     * 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
+     */
+    getObject<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
 }
 
-export { Toggle, type ToggleContext, ToggleHooks, type ToggleOptions, type ToggleRequestOptions };
+export { Toggle, type ToggleCachingOptions, type ToggleContext, type ToggleGetOptions, ToggleHooks, type ToggleOptions };

package/dist/index.js

@@ -2,7 +2,7 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/toggle.ts
-import process from "node:process";
+import process from "process";
 import { Hookified } from "hookified";
 import { OpenFeature } from "@openfeature/server-sdk";
 import { HyphenProvider } from "@hyphen/openfeature-server-provider";
@@ -22,73 +22,178 @@ var Toggle = class extends Hookified {
     __name(this, "Toggle");
   }
   _applicationId;
-  _publicKey;
+  _publicApiKey = "";
   _environment;
   _client;
   _context;
   _throwErrors = false;
   _uris;
+  _caching;
+  /*
+   * Create a new Toggle instance. This will create a new client and set the options.
+   * @param {ToggleOptions}
+  */
   constructor(options) {
     super();
     this._applicationId = options.applicationId;
-    this._publicKey = options.publicKey;
+    this.setPublicApiKey(options.publicApiKey);
     this._environment = options.environment ?? process.env.NODE_ENV ?? "development";
     this._context = options.context;
     this._throwErrors = options.throwErrors ?? false;
     this._uris = options.uris;
+    this._caching = options.caching;
   }
+  /**
+  * Get the application ID
+  * @returns {string}
+  */
   get applicationId() {
     return this._applicationId;
   }
+  /**
+  * Set the application ID
+  * @param {string} value
+  */
   set applicationId(value) {
     this._applicationId = value;
   }
-  get publicKey() {
-    return this._publicKey;
+  /**
+  * Get the public API key
+  * @returns {string}
+  */
+  get publicApiKey() {
+    return this._publicApiKey;
   }
-  set publicKey(value) {
-    this._publicKey = value;
+  /**
+  * Set the public API key
+  * @param {string} value
+  */
+  set publicApiKey(value) {
+    this.setPublicApiKey(value);
   }
+  /**
+  * Get the environment
+  * @returns {string}
+  */
   get environment() {
     return this._environment;
   }
+  /**
+  * Set the environment
+  * @param {string} value
+  */
   set environment(value) {
     this._environment = value;
   }
+  /**
+  * Get the throwErrors. If true, errors will be thrown in addition to being emitted.
+  * @returns {boolean}
+  */
   get throwErrors() {
     return this._throwErrors;
   }
+  /**
+  * Set the throwErrors. If true, errors will be thrown in addition to being emitted.
+  * @param {boolean} value
+  */
   set throwErrors(value) {
     this._throwErrors = value;
   }
+  /**
+  * Get the current context. This is the default context used. You can override this at the get function level.
+  * @returns {ToggleContext}
+  */
   get context() {
     return this._context;
   }
+  /**
+  * Set the context. This is the default context used. You can override this at the get function level.
+  * @param {ToggleContext} value
+  */
   set context(value) {
     this._context = value;
   }
+  /**
+  * 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>}
+  */
   get uris() {
     return this._uris;
   }
+  /**
+  * 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
+  */
   set uris(value) {
     this._uris = value;
   }
+  /**
+  * Get the caching options.
+  * @returns {ToggleCachingOptions | undefined}
+  */
+  get caching() {
+    return this._caching;
+  }
+  /**
+  * Set the caching options.
+  * @param {ToggleCachingOptions | undefined} value
+  */
+  set caching(value) {
+    this._caching = value;
+  }
+  /**
+  * 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
+  */
+  setPublicApiKey(key) {
+    if (!key.startsWith("public_")) {
+      this.emit("error", new Error("Public API key should start with public_"));
+      if (process.env.NODE_ENV !== "production") {
+        console.error("Public API key should start with public_");
+      }
+      return;
+    }
+    this._publicApiKey = key;
+    this._client = void 0;
+  }
+  /**
+  * Set the context. This is the default context used. You can override this at the get function level.
+  * @param {ToggleContext} context
+  */
   setContext(context) {
     this._context = context;
     this._client = void 0;
   }
+  /**
+  * 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>}
+  */
   async getClient() {
     if (!this._client) {
       const options = {
         application: this._applicationId,
         environment: this._environment,
-        horizonUrls: this._uris
+        horizonUrls: this._uris,
+        cache: this._caching
       };
-      await OpenFeature.setProviderAndWait(new HyphenProvider(this._publicKey, options));
+      await OpenFeature.setProviderAndWait(new HyphenProvider(this._publicApiKey, options));
       this._client = OpenFeature.getClient(this._context);
     }
     return this._client;
   }
+  /**
+  * 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>}
+  */
   async get(key, defaultValue, options) {
     switch (typeof defaultValue) {
       case "boolean": {
@@ -105,6 +210,14 @@ var Toggle = class extends Hookified {
       }
     }
   }
+  /**
+  * 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
+  */
   async getBoolean(key, defaultValue, options) {
     try {
       const data = {
@@ -131,6 +244,13 @@ var Toggle = class extends Hookified {
     }
     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
+  */
   async getString(key, defaultValue, options) {
     try {
       const data = {
@@ -183,6 +303,14 @@ var Toggle = class extends Hookified {
     }
     return defaultValue;
   }
+  /**
+  * 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
+  */
   async getObject(key, defaultValue, options) {
     try {
       const data = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyphen/sdk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Hyphen SDK for Node.js",
   "type": "module",
   "main": "dist/index.cjs",
@@ -29,15 +29,15 @@
   "author": "Team Hyphen <hello@hyphen.ai>",
   "license": "MIT",
   "devDependencies": {
-    "@swc/core": "^1.11.24",
-    "@types/node": "^22.15.17",
-    "@vitest/coverage-v8": "^3.1.3",
+    "@swc/core": "^1.11.29",
+    "@types/node": "^22.15.21",
+    "@vitest/coverage-v8": "^3.1.4",
     "rimraf": "^6.0.1",
     "tsd": "^0.32.0",
-    "tsup": "^8.4.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.3",
-    "xo": "^0.60.0"
+    "vitest": "^3.1.4",
+    "xo": "^1.0.0"
   },
   "files": [
     "dist",