@hyphen/sdk 1.8.0 → 1.10.0

package/README.md

@@ -11,8 +11,8 @@ The Hyphen Node.js SDK is a JavaScript library that allows developers to easily
 
 # Table of Contents
 - [Installation](#installation)
-- [Basic Usage](#basic-usage)
-- [Toggle](#toggle)
+- [Basic Usage with Hyphen](#basic-usage-with-hyphen)
+- [Toggle - Feature Flag Service](#toggle---feature-flag-service)
 	- [Toggle Options](#toggle-options)
 	- [Toggle API](#toggle-api)
 	- [Toggle Hooks](#toggle-hooks)
@@ -20,9 +20,10 @@ The Hyphen Node.js SDK is a JavaScript library that allows developers to easily
 	- [Toggle Caching](#toggle-caching)
 	- [Toggle Environment Variables](#toggle-environment-variables)
 	- [Toggle Self-Hosted](#toggle-self-hosted)
-- [ENV](#env)
+- [ENV - Secret Management Service](#env---secret-management-service)
 	- [Loading Environment Variables](#loading-environment-variables)
-- [Net Info](#net-info)
+- [Net Info - Geo Information Service](#net-info---geo-information-service)
+- [Link - Short Code Service](#link---short-code-service)
 - [Contributing](#contributing)
 - [Testing Your Changes](#testing-your-changes)
 - [License and Copyright](#license-and-copyright)
@@ -35,11 +36,95 @@ To install the Hyphen Node.js SDK, you can use npm or yarn. Run the following co
 npm install @hyphen/sdk
 ```
 
-# Basic Usage
+# Basic Usage with Hyphen
 
-There are many ways to use the Hyphen Node.js SDK. Because of this we have created examples for each of the different ways in each secton of the documentation.
+There are many ways to use the Hyphen Node.js SDK. Because of this we have created examples for each of the different ways in each secton of the documentation. To get started, you can create an instance of the `Hyphen` class and use its methods to interact with the various services.
 
-# Toggle
+```javascript
+import { Hyphen } from '@hyphen/sdk';
+
+const hyphen = new Hyphen({
+	publicApiKey: 'your_public_api_key',
+	applicationId: 'your_application_id',
+});
+const result = await hyphen.toggle.getBoolean('hyphen-sdk-boolean', false);
+console.log('Boolean toggle value:', result); // true
+```
+
+You can also use `netInfo` to access the network information service.
+
+```javascript
+import { Hyphen, 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 hyphen = new Hyphen({
+	publicApiKey: 'your_public_api_key',
+	toggle: {
+		applicationId: 'your_application_id',
+		context: context,
+	},
+});
+const result = await hyphen.toggle.getBoolean('hyphen-sdk-boolean', false);
+console.log('Boolean toggle value:', result); // true
+```
+
+You can also use `netInfo` to access the network information service.
+
+```javascript
+import { Hyphen } from '@hyphen/sdk';
+
+const hyphen = new Hyphen({
+	apiKey: 'your_api_key',
+});
+const result = await hyphen.netInfo.getIpInfo('8.8.8.8');
+console.log('Geo IP information:', result);
+```
+
+If you need to set the `apiKey` or `publicApiKey` after initializing `Hyphen` you can do so and it will cascade the setting to the individual services:
+
+```javascript
+import { Hyphen } from '@hyphen/sdk';
+
+const hyphen = new Hyphen();
+hyphen.apiKey = 'your_api_key';
+const result = await hyphen.netInfo.getIpInfo('8.8.8.8');
+console.log('Geo IP information:', result);
+```
+
+Finally, `error`, `warn`, and `info` emitters are enabled from each of the services and you can access them by doing the following example with `error`:
+
+```javascript
+import { Hyphen } from '@hyphen/sdk';
+
+const hyphen = new Hyphen({ apiKey: 'your_api_key'});
+
+hyphen.on('error', (error) => {
+	console.log(error);
+});
+
+const result = await hyphen.netInfo.getIpInfo('8.8.8.8');
+console.log('Geo IP information:', result);
+```
+
+The rest of the examples for each service show you accessing the service instance directly. 
+
+# Toggle - Feature Flag Service
 
 [Toggle](https://hyphen.ai/toggle) is our feature flag service that allows you to control the rollout of new features to your users. You can access your feature flags using the `Toggle` class.
 
@@ -487,7 +572,7 @@ const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
 console.log('Boolean toggle value:', result); // true
 ```
 
-# ENV
+# ENV - Secret Management Service
 
 Hyphens secret management service known as [ENV](https://hyphen.ai/env) allows you to manage your environment variables in a secure way. The Hyphen Node.js SDK provides a simple way to access your environment variables.
 
@@ -532,7 +617,7 @@ import { loadEnv } from '@hyphen/sdk';
 loadEnv({ local: false });
 ```
 
-# Net Info
+# Net Info - Geo Information Service
 
 The Hyphen Node.js SDK also provides a `NetInfo` class that allows you to fetch geo information about an IP address. This can be useful for debugging or logging purposes. You can read more about it:
 
@@ -566,6 +651,38 @@ console.log('IP Infos:', ipInfos);
 
 You can also set the API key using the `HYPHEN_API_KEY` environment variable. This is useful for keeping your API key secure and not hardcoding it in your code.
 
+# Link - Short Code Service
+
+The Hyphen Node.js SDK also provides a `Link` class that allows you to create and manage short codes. This can be useful for generating short links for your application. Here is an example of creating a short code:
+
+```javascript
+import { Link } from '@hyphen/sdk';
+const link = new Link({
+  organizationId: 'your_organization_id',
+  apiKey: 'your_api_key',
+});
+const longUrl = 'https://hyphen.ai';
+const domain = 'test.h4n.link';
+const options = {
+  tags: ['sdk-test', 'unit-test'],
+};
+const response = await link.createShortCode(longUrl, domain, options);
+console.log('Short Code Response:', response);
+```
+
+if you want to delete a short code you can do it like this:
+
+```javascript
+import { Link } from '@hyphen/sdk';
+const link = new Link({
+  organizationId: 'your_organization_id',
+  apiKey: 'your_api_key',
+});
+const code = 'code_1234567890'; // It is the code identifier for the short code you want to delete
+const response = await link.deleteShortCode(code);
+console.log('Delete Short Code Response:', response);
+```
+
 # Contributing
 
 We welcome contributions to the Hyphen Node.js SDK! If you have an idea for a new feature, bug fix, or improvement, please follow these steps:
@@ -606,9 +723,19 @@ Once you have created the project, added the toggles, and created your applicati
 HYPHEN_PUBLIC_API_KEY=your_public_api_key
 HYPHEN_API_KEY=your_api_key
 HYPHEN_APPLICATION_ID=your_project_id
+HYPHEN_LINK_DOMAIN=your_link_domain
+HYPHEN_ORGANIZATION_ID=your_organization_id
 ```
 
-The `HYPHEN_PUBLIC_API_KEY` is the public API key for your Hyphen project, `HYPHEN_API_KEY` is the API key used for things such as `NetInfo` and is located under settings in the dashboard, and `HYPHEN_APPLICATION_ID` is the application ID for your Hyphen project.
+A bit more information about the environment variables:
+
+| Variable | Example Value | Description |
+|----------------|----------------|----------------|
+| *HYPHEN_PUBLIC_API_KEY* | `public_api_key` | The public API key for your Hyphen project. You can find this in the Hyphen dashboard. |
+| *HYPHEN_API_KEY* | `api_key` | The API key for your Hyphen project. You can find this in the Hyphen dashboard. |
+| *HYPHEN_APPLICATION_ID* | `application_id` | The application ID for your Hyphen project. You can find this in the Hyphen dashboard. |
+| *HYPHEN_LINK_DOMAIN* | `test.h4n.link` | The domain for the Link service. This is used for generating links. |
+| *HYPHEN_ORGANIZATION_ID* | `org_668575c0e169cde974a5c76a` | | The organization ID for your Hyphen project. This is used for the Link service. |
 
 Then run the tests with the following command:
 

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Hyphen: () => Hyphen,
   Toggle: () => Toggle,
   ToggleHooks: () => ToggleHooks,
   loadEnv: () => loadEnv
@@ -442,8 +443,471 @@ function loadEnv(options) {
   }
 }
 __name(loadEnv, "loadEnv");
+
+// src/hyphen.ts
+var import_hookified3 = require("hookified");
+
+// src/net-info.ts
+var import_node_process3 = __toESM(require("process"), 1);
+
+// src/base-service.ts
+var import_hookified2 = require("hookified");
+var import_cacheable = require("cacheable");
+var import_axios = __toESM(require("axios"), 1);
+var import_pino = __toESM(require("pino"), 1);
+var ErrorMessages = /* @__PURE__ */ function(ErrorMessages2) {
+  ErrorMessages2["API_KEY_REQUIRED"] = "API key is required. Please provide it via options or set the HYPHEN_API_KEY environment variable.";
+  ErrorMessages2["PUBLIC_API_KEY_SHOULD_NOT_BE_USED"] = "The provided API key is a public API key. Please provide a valid non public API key for authentication.";
+  return ErrorMessages2;
+}({});
+var BaseService = class extends import_hookified2.Hookified {
+  static {
+    __name(this, "BaseService");
+  }
+  _log = (0, import_pino.default)();
+  _cache = new import_cacheable.Cacheable();
+  _throwErrors = false;
+  constructor(options) {
+    super(options);
+    if (options && options.throwErrors !== void 0) {
+      this._throwErrors = options.throwErrors;
+    }
+  }
+  get log() {
+    return this._log;
+  }
+  set log(value) {
+    this._log = value;
+  }
+  get cache() {
+    return this._cache;
+  }
+  set cache(value) {
+    this._cache = value;
+  }
+  get throwErrors() {
+    return this._throwErrors;
+  }
+  set throwErrors(value) {
+    this._throwErrors = value;
+  }
+  error(message, ...args) {
+    this._log.error(message, ...args);
+    this.emit("error", message, ...args);
+    if (this.throwErrors) {
+      throw new Error(message);
+    }
+  }
+  warn(message, ...args) {
+    this._log.warn(message, ...args);
+    this.emit("warn", message, ...args);
+  }
+  info(message, ...args) {
+    this._log.info(message, ...args);
+    this.emit("info", message, ...args);
+  }
+  async get(url, config2) {
+    return import_axios.default.get(url, config2);
+  }
+  async post(url, data, config2) {
+    return import_axios.default.post(url, data, config2);
+  }
+  async put(url, data, config2) {
+    return import_axios.default.put(url, data, config2);
+  }
+  async delete(url, config2) {
+    return import_axios.default.delete(url, config2);
+  }
+  async patch(url, data, config2) {
+    return import_axios.default.patch(url, data, config2);
+  }
+  createHeaders(apiKey) {
+    const headers = {
+      "content-type": "application/json",
+      accept: "application/json"
+    };
+    if (apiKey) {
+      headers["x-api-key"] = apiKey;
+    }
+    return headers;
+  }
+};
+
+// src/net-info.ts
+loadEnv();
+var NetInfo = class extends BaseService {
+  static {
+    __name(this, "NetInfo");
+  }
+  _apiKey;
+  _baseUri = "https://net.info";
+  constructor(options) {
+    super(options);
+    if (options?.baseUri) {
+      this._baseUri = options.baseUri;
+    }
+    this.setApiKey(options?.apiKey);
+    if (!this._apiKey && import_node_process3.default.env.HYPHEN_API_KEY) {
+      this.setApiKey(import_node_process3.default.env.HYPHEN_API_KEY);
+    }
+    if (!this._apiKey) {
+      this.error(ErrorMessages.API_KEY_REQUIRED);
+    }
+  }
+  /**
+   * Gets or sets the API key for authentication.
+   * If not set, it will try to use the `HYPHEN_API_KEY` environment variable.
+   * @type {string | undefined}
+   */
+  get apiKey() {
+    return this._apiKey;
+  }
+  /**
+   * Sets the API key for authentication.
+   * @param {string | undefined} value - The API key to set.
+   */
+  set apiKey(value) {
+    this.setApiKey(value);
+  }
+  /**
+   * Gets or sets the base URI for the API.
+   * @type {string}
+   */
+  get baseUri() {
+    return this._baseUri;
+  }
+  /**
+   * Sets the base URI for the API.
+   * @param {string} value - The base URI to set.
+   */
+  set baseUri(value) {
+    this._baseUri = value;
+  }
+  setApiKey(value) {
+    if (value?.startsWith("public_")) {
+      this.error(ErrorMessages.PUBLIC_API_KEY_SHOULD_NOT_BE_USED);
+      return;
+    }
+    this._apiKey = value;
+  }
+  /**
+   * Fetches GeoIP information for a given IP address.
+   * @param {string} ip - The IP address to fetch GeoIP information for.
+   * @returns {Promise<ipInfo | ipInfoError>} - A promise that resolves to the ip information or an error.
+   */
+  async getIpInfo(ip) {
+    try {
+      if (!this._apiKey) {
+        throw new Error(ErrorMessages.API_KEY_REQUIRED);
+      }
+      const url = `${this._baseUri}/ip/${ip}`;
+      const headers = this.createHeaders(this._apiKey);
+      const response = await this.get(url, {
+        headers
+      });
+      if (response.status !== 200) {
+        const errorResult = {
+          ip,
+          type: "error",
+          errorMessage: `Failed to fetch ip info: ${response.statusText}`
+        };
+        return errorResult;
+      }
+      return response.data;
+    } catch (error) {
+      this.error(`Failed to fetch ip info: ${error instanceof Error ? error.message : "Unknown error"}`);
+      const errorResult = {
+        ip,
+        type: "error",
+        errorMessage: error instanceof Error ? error.message : "Unknown error"
+      };
+      return errorResult;
+    }
+  }
+  async getIpInfos(ips) {
+    if (!Array.isArray(ips) || ips.length === 0) {
+      this.error("The provided IPs array is invalid. It should be a non-empty array of strings.");
+      return [];
+    }
+    const errorResults = [];
+    try {
+      if (!this._apiKey) {
+        throw new Error(ErrorMessages.API_KEY_REQUIRED);
+      }
+      const url = `${this._baseUri}/ip`;
+      const headers = this.createHeaders(this._apiKey);
+      const response = await this.post(url, ips, {
+        headers
+      });
+      if (response.status !== 200) {
+        errorResults.push({
+          ip: "",
+          type: "error",
+          errorMessage: `Failed to fetch ip infos: ${response.statusText}`
+        });
+        return errorResults;
+      }
+      const responseData = response?.data;
+      return responseData.data;
+    } catch (error) {
+      this.error(`Failed to fetch ip infos: ${error instanceof Error ? error.message : "Unknown error"}`);
+      errorResults.push({
+        ip: "",
+        type: "error",
+        errorMessage: error instanceof Error ? error.message : "Unknown error"
+      });
+      return errorResults;
+    }
+  }
+};
+
+// src/link.ts
+var import_node_process4 = __toESM(require("process"), 1);
+loadEnv();
+var defaultLinkUris = [
+  "https://api.hyphen.ai/api/organizations/{organizationId}/link/codes/"
+];
+var Link = class extends BaseService {
+  static {
+    __name(this, "Link");
+  }
+  _uris = defaultLinkUris;
+  _organizationId;
+  _apiKey;
+  constructor(options) {
+    super(options);
+    this._uris = options?.uris ?? defaultLinkUris;
+    this._organizationId = options?.organizationId;
+    if (options?.apiKey) {
+      this.setApiKey(options.apiKey);
+    }
+    if (!this._apiKey && import_node_process4.default.env.HYPHEN_API_KEY) {
+      this.setApiKey(import_node_process4.default.env.HYPHEN_API_KEY);
+    }
+    if (!this._organizationId && import_node_process4.default.env.HYPHEN_ORGANIZATION_ID) {
+      this._organizationId = import_node_process4.default.env.HYPHEN_ORGANIZATION_ID;
+    }
+  }
+  /**
+  * Get the URIs for the link service. The default is `["https://api.hyphen.ai/api/organizations/{organizationId}/link/codes/"]`.
+  * @returns {string[]} The URIs for the link service.
+  */
+  get uris() {
+    return this._uris;
+  }
+  /**
+  * Set the URIs for the link service. The default is `["https://api.hyphen.ai/api/organizations/{organizationId}/link/codes/"]`.
+  * @param {string[]} uris - The URIs to set.
+  */
+  set uris(uris) {
+    this._uris = uris;
+  }
+  /**
+  * Get the organization ID for the link service. This is required to access the link service.
+  * @returns {string | undefined} The organization ID.
+  */
+  get organizationId() {
+    return this._organizationId;
+  }
+  /**
+  * Set the organization ID for the link service. This is required to access the link service.
+  * @param {string | undefined} organizationId - The organization ID to set.
+  */
+  set organizationId(organizationId) {
+    this._organizationId = organizationId;
+  }
+  /**
+  * Get the API key for the link service. This is required to access the link service.
+  * @returns {string | undefined} The API key.
+  */
+  get apiKey() {
+    return this._apiKey;
+  }
+  /**
+  * Set the API key for the link service. This is required to access the link service.
+  * @param {string | undefined} apiKey - The API key to set.
+  */
+  set apiKey(apiKey) {
+    this.setApiKey(apiKey);
+  }
+  /**
+  * Set the API key for the link service. If the API key starts with 'public_', an error is thrown.
+  * This is to ensure that the API key is not a public key, which should not be used for authenticated requests.
+  * @param {string} apiKey
+  */
+  setApiKey(apiKey) {
+    if (apiKey?.startsWith("public_")) {
+      throw new Error('API key cannot start with "public_"');
+    }
+    if (apiKey) {
+      this._apiKey = apiKey;
+    }
+  }
+  async createShortCode(longUrl, domain, options) {
+    if (!this._organizationId) {
+      throw new Error("Organization ID is required to create a short code.");
+    }
+    const url = this._uris[0].replace("{organizationId}", this._organizationId);
+    const body = {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      long_url: longUrl,
+      domain,
+      code: options?.code,
+      title: options?.title,
+      tags: options?.tags
+    };
+    const headers = this.createHeaders(this._apiKey);
+    const response = await this.post(url, body, {
+      headers
+    });
+    if (response.status === 201) {
+      return response.data;
+    }
+    throw new Error(`Failed to create short code: ${response.statusText}`);
+  }
+  /**
+  * Delete a short code.
+  * @param {string} code The short code to delete. Example: 'code_686bed403c3991bd676bba4d'
+  * @returns {Promise<boolean>} A promise that resolves to true if the short code was deleted successfully, or false if it was not.
+  */
+  async deleteShortCode(code) {
+    if (!this._organizationId) {
+      throw new Error("Organization ID is required to delete a short code.");
+    }
+    let url = this._uris[0].replace("{organizationId}", this._organizationId);
+    url = url.endsWith("/") ? `${url}${code}/` : `${url}/${code}/`;
+    const headers = this.createHeaders(this._apiKey);
+    delete headers["content-type"];
+    const response = await this.delete(url, {
+      headers
+    });
+    if (response.status === 204) {
+      return true;
+    }
+    throw new Error(`Failed to delete short code: ${response.statusText}`);
+  }
+};
+
+// src/hyphen.ts
+var Hyphen = class extends import_hookified3.Hookified {
+  static {
+    __name(this, "Hyphen");
+  }
+  _netInfo;
+  _toggle;
+  _link;
+  _publicApiKey;
+  _apiKey;
+  constructor(options) {
+    super(options);
+    const toggleOptions = options?.toggle ?? {};
+    const netInfoOptions = options?.netInfo ?? {};
+    const linkOptions = options?.link ?? {};
+    if (options?.publicApiKey) {
+      this._publicApiKey = options.publicApiKey;
+      toggleOptions.publicApiKey = options.publicApiKey;
+    }
+    if (options?.apiKey) {
+      this._apiKey = options.apiKey;
+      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));
+    this._netInfo.on("warn", (message, ...args) => this.emit("warn", message, ...args));
+    this._toggle = new Toggle(toggleOptions);
+    this._toggle.on("error", (message, ...args) => this.emit("error", message, ...args));
+    this._toggle.on("info", (message, ...args) => this.emit("info", message, ...args));
+    this._toggle.on("warn", (message, ...args) => this.emit("warn", message, ...args));
+    this._link = new Link(linkOptions);
+    this._link.on("error", (message, ...args) => this.emit("error", message, ...args));
+    this._link.on("info", (message, ...args) => this.emit("info", message, ...args));
+    this._link.on("warn", (message, ...args) => this.emit("warn", message, ...args));
+  }
+  /**
+  * Get the NetInfo service instance.
+  * @returns {NetInfo} The NetInfo service instance.
+  */
+  get netInfo() {
+    return this._netInfo;
+  }
+  /**
+  * Get the Toggle service instance.
+  * @returns {Toggle} The Toggle service instance.
+  */
+  get toggle() {
+    return this._toggle;
+  }
+  /**
+  * Get the Link service instance.
+  * @returns {Link} The Link service instance.
+  */
+  get link() {
+    return this._link;
+  }
+  /**
+  * Get the public API key for the Hyphen service.
+  * This is used for public endpoints that do not require authentication.
+  * @returns {string | undefined} The public API key.
+  */
+  get publicApiKey() {
+    return this._publicApiKey;
+  }
+  /**
+  * Set the public API key for the Hyphen service. If set, this will also update the underlying services.
+  * This is used for public endpoints that do not require authentication such as the Toggle service.
+  * @param {string | undefined} value - The public API key to set.
+  */
+  set publicApiKey(value) {
+    this._publicApiKey = value;
+    this._toggle.publicApiKey = value;
+  }
+  /**
+  * Get the API key for the Hyphen service.
+  * This is used for authenticated endpoints that require an API key such as the NetInfo and Link services.
+  * @returns {string | undefined} The API key.
+  */
+  get apiKey() {
+    return this._apiKey;
+  }
+  /**
+  * Set the API key for the Hyphen service. If set, this will also update the underlying services.
+  * This is used for authenticated endpoints that require an API key such as the NetInfo and Link services.
+  * @param {string | undefined} value - The API key to set.
+  */
+  set apiKey(value) {
+    this._apiKey = value;
+    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,
   loadEnv