@hyphen/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hyphen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+![Hyphen AI](logo.svg)
+
+[![tests](https://github.com/Hyphen/nodejs-sdk/actions/workflows/tests.yaml/badge.svg)](https://github.com/Hyphen/nodejs-sdk/actions/workflows/tests.yaml)
+[![npm](https://img.shields.io/npm/v/@hyphen/sdk)](https://www.npmjs.com/package/@hyphen/sdk)
+[![npm](https://img.shields.io/npm/dm/@hyphen/sdk)](https://www.npmjs.com/package/@hyphen/sdk)
+[![license](https://img.shields.io/github/license/Hyphen/nodejs-sdk)](https://github.com/hyphen/nodejs-sdk/blob/main/LICENSE)
+
+# Hyphen Node.js SDK
+
+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.
+
+# Installation
+
+To install the Hyphen Node.js SDK, you can use npm or yarn. Run the following command in your terminal:
+
+```bash
+npm install @hyphen/sdk
+```
+
+# Usage
+
+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.
+
+# Toggle
+
+[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.
+
+```javascript
+import { Toggle, Context } from '@hyphen/sdk';
+
+const context: Context = {
+	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,
+};
+
+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 set the context you can do it like this:
+
+```javascript
+import { Toggle, Context } from '@hyphen/sdk';
+
+const context: Context = {
+	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',
+};
+
+const toggle = new Toggle(toggleOptions);
+
+toggle.setContext(context);
+
+const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
+
+console.log('Boolean toggle value:', result); // true
+```
+
+if you would like to override the context for a single request you can do it like this:
+
+```javascript
+import { Toggle, Context } from '@hyphen/sdk';
+
+const context: Context = {
+	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,
+};
+
+const overrideContext: Context = {
+	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 toggle = new Toggle(toggleOptions);
+
+const result = await toggle.getBoolean('hyphen-sdk-boolean', false, { context: overrideContext });
+
+console.log('Boolean toggle value:', result); // true
+```
+
+## Toggle Options
+
+| Option | Type | Description |
+|----------------|----------------|----------------|
+| *publicApiKey* | ` string` | The public API key for your Hyphen project. You can find this in the Hyphen dashboard. |
+| *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?* | `Context` | The context object that contains the user and custom attributes. This is optional. |
+| *cache?* | `{ ttl: number}` | Whether to use the cache or not. |
+
+## Toggle API
+
+| Method | Parameters | Description |
+|----------------|----------------|----------------|
+| *setContext* | `context: Context` | Set the context for the toggle. This is optional. |
+| *get<Type>* | `key: string, defaultValue: T, options?: { context?: Context }` | 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?: { context?: Context }` | Get the value of a boolean toggle. |
+| *getNumber* | `key: string, defaultValue: number, options?: { context?: Context }` | Get the value of a number toggle. |
+| *getString* | `key: string, defaultValue: string, options?: { context?: Context }` | Get the value of a string toggle. |
+| *getObject<Type>* | `key: string, defaultValue: any, options?: { context?: Context }` | 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. |
+
+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.
+
+```javascript
+import { Toggle, ToggleHooks, Context } from '@hyphen/sdk';
+
+const context: Context = {
+	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,
+};
+
+const toggle = new Toggle(toggleOptions);
+
+toggle.onHook(ToggleHooks.beforeGetBoolean, (data) => {
+  console.log('Before get boolean toggle:', data); // { key: 'hyphen-sdk-boolean', defaultValue: false }
+});
+
+const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
+
+console.log('Boolean toggle value:', result); // true
+```
+
+# 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:
+
+## Testing Your Changes
+
+To test your changes locally you will need to create an account on [Hyphen](https://hyphen.ai) and do the following:
+1. Create a new project in the Hyphen dashboard. This will give you a project ID and an Public API key.
+2. On the project please add the following toggles:
+
+
+| Name | Type | Value |
+|----------------|----------------|----------------|
+| hyphen-sdk-boolean | boolean | true |
+| hyphen-sdk-number | number | 42 |
+| hyphen-sdk-string | string | "Hyphen!" |
+| hyphen-sdk-json | json | `{ "id": "Hello World!"}` |
+
+Then, create a new application in the project. This will give you an application ID.
+
+Once you have created the project, added the toggles, and created your application you can run the tests then create an `.env` file in the root of the project with the following content:
+
+
+```bash
+HYPHEN_PUBLIC_API_KEY=your_api_key
+HYPHEN_APPLICATION_ID=your_project_id
+```
+
+Then run the tests with the following command:
+
+```bash
+pnpm i && pnpm test
+```
+
+# License and Copyright
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+The copyright for this project is held by Hyphen, Inc. All rights reserved.

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { Hookified } from 'hookified';
+import { EvaluationContext, Client } from '@openfeature/server-sdk';
+
+type Context = EvaluationContext;
+type ToggleOptions = {
+    /**
+     * Your application name
+     * @type {string}
+     */
+    applicationId: string;
+    /**
+     * Your Hyphen API key
+     * @type {string}
+     */
+    publicKey: string;
+    /**
+     * Your environment name such as development, production. Default is what is set at NODE_ENV
+     * @type {string}
+     * @example production
+     */
+    environment?: string;
+    /**
+     * The context to use for evaluating feature flags
+     * @type {Context}
+     */
+    context?: Context;
+    caching?: {
+        /**
+         * The time in seconds to cache the feature flag values
+         * @type {number} - this is in milliseconds
+         */
+        ttl?: number;
+    };
+};
+type ToggleRequestOptions = {
+    context?: Context;
+};
+declare class Toggle extends Hookified {
+    private _applicationId;
+    private _publicKey;
+    private _environment;
+    private _client;
+    private _context;
+    constructor(options: ToggleOptions);
+    get applicationId(): string;
+    set applicationId(value: string);
+    get publicKey(): string;
+    set publicKey(value: string);
+    get environment(): string;
+    set environment(value: string);
+    setContext(context: Context): void;
+    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>;
+}
+
+export { Toggle };

package/dist/index.js

@@ -0,0 +1,149 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/toggle.ts
+import process from "node:process";
+import { Hookified } from "hookified";
+import { OpenFeature } from "@openfeature/server-sdk";
+import { HyphenProvider } from "@hyphen/openfeature-server-provider";
+var Toggle = class extends Hookified {
+  static {
+    __name(this, "Toggle");
+  }
+  _applicationId;
+  _publicKey;
+  _environment;
+  _client;
+  _context;
+  constructor(options) {
+    super();
+    this._applicationId = options.applicationId;
+    this._publicKey = options.publicKey;
+    this._environment = options.environment ?? process.env.NODE_ENV ?? "development";
+    this._context = options.context;
+  }
+  get applicationId() {
+    return this._applicationId;
+  }
+  set applicationId(value) {
+    this._applicationId = value;
+  }
+  get publicKey() {
+    return this._publicKey;
+  }
+  set publicKey(value) {
+    this._publicKey = value;
+  }
+  get environment() {
+    return this._environment;
+  }
+  set environment(value) {
+    this._environment = value;
+  }
+  setContext(context) {
+    this._context = context;
+    this._client = void 0;
+  }
+  async getClient() {
+    if (!this._client) {
+      const options = {
+        application: this._applicationId,
+        environment: this._environment
+      };
+      await OpenFeature.setProviderAndWait(new HyphenProvider(this._publicKey, options));
+      this._client = OpenFeature.getClient(this._context);
+    }
+    return this._client;
+  }
+  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);
+      }
+    }
+  }
+  async getBoolean(key, defaultValue, options) {
+    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;
+  }
+  async getString(key, defaultValue, options) {
+    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;
+  }
+  async getNumber(key, defaultValue, options) {
+    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;
+  }
+  async getObject(key, defaultValue, options) {
+    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;
+  }
+};
+export {
+  Toggle
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hyphen/sdk",
+  "version": "1.0.0",
+  "description": "Hyphen SDK for Node.js",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "types": "dist/node/index.d.ts",
+  "keywords": [
+    "hyphen",
+    "sdk",
+    "nodejs",
+    "javascript",
+    "typescript"
+  ],
+  "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",
+    "rimraf": "^6.0.1",
+    "tsd": "^0.32.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.3",
+    "xo": "^0.60.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@hyphen/openfeature-server-provider": "^1.0.7",
+    "@openfeature/server-sdk": "^1.18.0",
+    "dotenv": "^16.5.0",
+    "hookified": "^1.9.0"
+  },
+  "scripts": {
+    "test": "xo --fix && vitest run --coverage",
+    "test:ci": "xo && vitest run --coverage",
+    "build": "rimraf ./dist && tsup src/index.ts --format esm,cjs --dts --clean",
+    "clean": "rimraf ./dist"
+  }
+}