@configdirector/nuxt-sdk 0.1.0

package/dist/runtime/plugin.server.d.mts

@@ -0,0 +1,4 @@
+//#region src/runtime/plugin.server.d.ts
+declare const _default: any;
+//#endregion
+export { _default as default };

package/dist/runtime/plugin.server.mjs

@@ -0,0 +1,106 @@
+import { consola } from "consola";
+import { readonly, shallowRef, toRaw } from "vue";
+import { defineNuxtPlugin, useNuxtApp, useRuntimeConfig, useState } from "#app";
+//#region src/runtime/logger.ts
+const createDefaultLogger = (level) => {
+	const logger = consola.withTag("configdirector-nuxt-sdk");
+	if (level !== void 0) logger.level = level;
+	return logger;
+};
+//#endregion
+//#region src/runtime/app/composables/useConfigDirectorClient.ts
+const useConfigDirectorClient = () => {
+	const { $configDirectorClient } = useNuxtApp();
+	return { client: $configDirectorClient };
+};
+//#endregion
+//#region src/runtime/app/composables/useConfigDirectorContext.ts
+const DEFAULT_TIMEOUT = 3e3;
+const getEffectiveTimeout = (option) => {
+	return option && option > 0 ? option : DEFAULT_TIMEOUT;
+};
+const useConfigDirectorContext = () => {
+	const state = useState("configdirector-context");
+	const { client } = useConfigDirectorClient();
+	const updateContext = async (context, options) => {
+		const rawContext = toRaw(context);
+		const oldContext = JSON.stringify(state.value);
+		const newContext = JSON.stringify(rawContext);
+		state.value = rawContext;
+		if (oldContext != newContext) {
+			const timeout = getEffectiveTimeout(options?.timeoutMilliseconds);
+			await Promise.race([client.updateContext(rawContext), new Promise((resolve) => {
+				setTimeout(() => resolve(), timeout);
+			})]);
+		}
+	};
+	return {
+		context: readonly(state),
+		updateContext
+	};
+};
+//#endregion
+//#region src/runtime/plugin.server.ts
+var plugin_server_default = defineNuxtPlugin((nuxtApp) => {
+	const logger = createDefaultLogger(useRuntimeConfig().configdirector?.logLevel);
+	logger.debug("Installed ConfigDirector Nuxt SSR plugin");
+	const serverSdkClient = nuxtApp.ssrContext?.event?.context.configDirectorClient;
+	logger.debug("Nitro ConfigDirector client isReady: ", serverSdkClient?.isReady);
+	if (!serverSdkClient) throw "The nitro ConfigDirector plugin was not initialized";
+	const client = createSsrClient(serverSdkClient);
+	const readyStatus = shallowRef(serverSdkClient.isReady ? "ready" : "default");
+	nuxtApp.hooks.hook("app:created", async () => {
+		logger.debug("Updating ConfigDirector context for SSR evaluation");
+		const { context } = useConfigDirectorContext();
+		await client.initialize(context.value);
+	});
+	return { provide: {
+		configDirectorClient: client,
+		configDirectorClientReadyStatus: readonly(readyStatus)
+	} };
+});
+var SsrClient = class {
+	currentContext;
+	constructor(serverClient) {
+		this.serverClient = serverClient;
+		this.serverClient = serverClient;
+	}
+	async initialize(context) {
+		this.currentContext = context;
+	}
+	async updateContext(context) {
+		this.currentContext = context;
+	}
+	get context() {
+		return this.currentContext;
+	}
+	get isReady() {
+		return this.serverClient.isReady;
+	}
+	get isInitializing() {
+		return false;
+	}
+	getValue(configKey, defaultValue) {
+		return this.serverClient.getValue(configKey, defaultValue, this.currentContext);
+	}
+	watch(configKey, defaultValue, callback) {
+		return this.serverClient.watch(configKey, defaultValue, callback, this.currentContext);
+	}
+	unwatch(configKey, callback) {
+		return this.serverClient.unwatch(configKey, callback);
+	}
+	unwatchAll() {
+		return this.serverClient.unwatchAll();
+	}
+	pauseNetwork() {}
+	async resumeNetwork() {}
+	dispose() {}
+	on() {}
+	off() {}
+	clear() {}
+};
+const createSsrClient = (serverClient) => {
+	return new SsrClient(serverClient);
+};
+//#endregion
+export { plugin_server_default as default };

package/dist/runtime/server/composables/useConfigDirectorClient.d.mts

@@ -0,0 +1,6 @@
+import { t as ConfigDirectorClient } from "../../types-D9MFb76Q.mjs";
+
+//#region src/runtime/server/composables/useConfigDirectorClient.d.ts
+declare const useConfigDirectorClient: () => ConfigDirectorClient;
+//#endregion
+export { useConfigDirectorClient };

package/dist/runtime/server/composables/useConfigDirectorClient.d.ts

@@ -0,0 +1,6 @@
+import { t as ConfigDirectorClient } from "../../types-D9MFb76Q.mjs";
+
+//#region src/runtime/server/composables/useConfigDirectorClient.d.ts
+declare const useConfigDirectorClient: () => ConfigDirectorClient;
+//#endregion
+export { useConfigDirectorClient };

package/dist/runtime/server/composables/useConfigDirectorClient.mjs

@@ -0,0 +1,9 @@
+import { useNitroApp } from "nitropack/runtime";
+//#region src/runtime/server/composables/useConfigDirectorClient.ts
+const useConfigDirectorClient = () => {
+	const serverSdkClient = useNitroApp().configDirectorClient;
+	if (!serverSdkClient) throw "The nitro ConfigDirector plugin was not initialized";
+	return serverSdkClient;
+};
+//#endregion
+export { useConfigDirectorClient };

package/dist/runtime/types-CQWNx-gI.d.mts

@@ -0,0 +1,34 @@
+//#region ../shared/src/types.d.ts
+type ConfigEnumLikeType = {
+  [key: string]: string | number;
+};
+type ConfigValueType = string | number | boolean | object | ConfigEnumLikeType;
+/**
+ * The user's context to be sent to ConfigDirector. This context will be used for targeting
+ * rules evaluation.
+ */
+type ConfigDirectorContext = {
+  /**
+   * The user's identifier. This should be a value that uniquely identifies an application
+   * user.
+   * In the case of anonymous users, you could generate a UUID or alternatively not provide
+   * the {@link id} and the SDK will generate a random UUID. However, keep in mind that this
+   * value is used for segmenting users in percentage rollouts, and changes to the {@link id}
+   * could result in the user being assigned to a different percentile.
+   */
+  id?: string;
+  /**
+   * The user's display name. This will be shown in the ConfigDirector dashboard and may be
+   * used for targeting rules.
+   */
+  name?: string;
+  /**
+   * Any arbitrary traits for the current user. They will be shown in the ConfigDirector
+   * dashboard and may be used for targeting rules.
+   */
+  traits?: {
+    [key: string]: unknown;
+  };
+};
+//#endregion
+export { ConfigValueType as n, ConfigDirectorContext as t };

package/dist/runtime/types-CkzBXJwA.d.mts

@@ -0,0 +1,4 @@
+//#region src/runtime/types.d.ts
+type ClientStatus = "loading" | "ready" | "default";
+//#endregion
+export { ClientStatus as t };

package/dist/runtime/types-D9MFb76Q.d.mts

@@ -0,0 +1,85 @@
+import { n as ConfigValueType, t as ConfigDirectorContext } from "./types-CQWNx-gI.mjs";
+
+//#region ../js-server-sdk/src/types.d.ts
+type ClientEvents = {
+  configsUpdated: {
+    keys: string[];
+  };
+  clientReady: undefined;
+};
+type WatchHandler<T extends ConfigValueType> = (message: T) => void;
+/**
+ * The ConfigDirector SDK client object.
+ *
+ * Applications should create a single instance of `ConfigDirectorClient`, and call
+ * {@link initialize} during application initialization.
+ */
+interface ConfigDirectorClient {
+  /**
+   * Initializes the connection to ConfigDirector to retrieve config definitions. Until
+   * initialization is successful, all flags will return their default value provided to
+   * {@link watch} or {@link getValue}.
+   *
+   * If the connection fails or is interrupted with a transient error (network error,
+   * internal server error, etc) the client will continue to attempt to connect. However,
+   * if the connection fails with a persistent error, like an invalid SDK key, the client will
+   * not attempt to re-connect and an error will be logged to the console or the provided
+   * logger.
+   */
+  initialize(): Promise<void>;
+  /**
+   * Returns whether or not the client is ready after calling {@link initialize}
+   *
+   * The definition of ready is that the connection to the server was successful, and config definitions
+   * were received.
+   */
+  get isReady(): boolean;
+  /**
+   * Evaluates a config and returns its value based on the current context and targeting rules
+   *
+   * @returns The evaluated config value, or the `defaultValue` if the config state was unavailable
+   * @param configKey The config key to evaluate
+   * @param defaultValue The default value to be returned if the config state is unavailable. For
+   * example, if the client cannot connect to the server due to network conditions, or if getValue
+   * is called before initialization is done.
+   * @param context The user's context to be used for targeting rules evaluation (optional)
+   */
+  getValue<T extends ConfigValueType>(configKey: string, defaultValue: T, context?: ConfigDirectorContext): T;
+  /**
+   * Watches for changes to a a config evaluation value. Whenever the config value changes, the
+   * provided callback function will be called with the new value. Changes can happen due to updates
+   * to the config in the ConfigDirector dashboard, or if the context is updated via {@link updateContext}.
+   *
+   * @returns An 'unwatch' function that can be called to remove the subscriber
+   *
+   * @param configKey The config key to watch
+   * @param defaultValue The default value to be referenced if the config state is unavailable
+   * @param callback The callback function to be called whenever the config value is updated
+   * @param context The user's context to be used for targeting rules evaluation (optional)
+   */
+  watch<T extends ConfigValueType>(configKey: string, defaultValue: T, callback: WatchHandler<T>, context?: ConfigDirectorContext): () => void;
+  /**
+   * Removes a particular subscriber to the given `configKey`, or all subscribers if no callback
+   * is provided.
+   *
+   * @param configKey The config key to remove subscribers from
+   * @param callback The subscriber to be removed. If not provided, all subscribers are removed for
+   * the given `configKey`.
+   */
+  unwatch<T extends ConfigValueType>(configKey: string, callback?: WatchHandler<T>): void;
+  /**
+   * Removes all subscribers from all config keys
+   */
+  unwatchAll(): void;
+  on<T extends keyof ClientEvents>(eventName: T, handler: (args: ClientEvents[T]) => void): void;
+  off<T extends keyof ClientEvents>(eventName: T, handler?: (args: ClientEvents[T]) => void): void;
+  /**
+   * Disposes of the client. All connections are closed, and all event and config key subscribers
+   * are removed.
+   *
+   * Intended to be called when your application shuts down
+   */
+  dispose(): void;
+}
+//#endregion
+export { ConfigDirectorClient as t };

package/dist/runtime/types-KSnINlzh.d.mts

@@ -0,0 +1,135 @@
+import { n as ConfigValueType, t as ConfigDirectorContext } from "./types-CQWNx-gI.mjs";
+
+//#region ../js-client-core/src/Emitter.d.ts
+type EventType = string | symbol;
+type EventsRecord = Record<EventType, any>;
+type Handler<TEventsRecord extends EventsRecord, TKey extends keyof TEventsRecord> = (payload: TEventsRecord[TKey]) => void;
+interface EventProvider<TEventsRecord extends EventsRecord> {
+  on<TName extends keyof TEventsRecord>(name: TName, handler: Handler<TEventsRecord, TName>): void;
+  off<TName extends keyof TEventsRecord>(name: TName, handler?: Handler<TEventsRecord, TName>): void;
+  clear(): void;
+}
+//#endregion
+//#region ../js-client-core/src/types.d.ts
+type ClientConnectAction = "initialization" | "context update" | "network resume";
+type ClientEvents = {
+  configsUpdated: {
+    keys: string[];
+  };
+  clientReady: {
+    action: ClientConnectAction;
+  };
+  contextUpdated: {
+    context: ConfigDirectorContext | undefined;
+  };
+};
+type WatchHandler<T extends ConfigValueType> = (message: T) => void;
+/**
+ * The ConfigDirector SDK client object.
+ *
+ * Applications should create a single instance of `ConfigDirectorClient`, and call
+ * {@link initialize} during application initialization.
+ *
+ * After initialization, to update the user's context, so that targeting rules are evaluated
+ * with the updated context, call {@link updateContext}.
+ */
+interface ConfigDirectorClient extends EventProvider<ClientEvents> {
+  /**
+   * Initializes the connection to ConfigDirector to retrieve config evaluations. Until
+   * initialization is successful, all flags will return their default value provided to
+   * {@link watch} or {@link getValue}.
+   *
+   * If the connection fails or is interrupted with a transient error (network error,
+   * internal server error, etc) the client will continue to attempt to connect. However,
+   * if the connection fails with a persistent error, like an invalid SDK key, the client will
+   * not attempt to re-connect and an error will be logged to the console or the provided
+   * logger.
+   *
+   * @param context The current user's context to be used for evaluating targeting rules (optional).
+   */
+  initialize(context?: ConfigDirectorContext): Promise<void>;
+  /**
+   * Updates the user's context and re-evaluates all config and flag values based on the new context.
+   *
+   * @param context The current user's context to be used for evaluating targeting rules (required).
+   */
+  updateContext(context: ConfigDirectorContext): Promise<void>;
+  /**
+   * Returns the current context the client is configured with, or undefined if there is no context.
+   *
+   * Note that the value returned does not updated immediately after calling {@link updateContext}. Only
+   * once the underlying connection was successful or timed out, the current context is updated. This is
+   * because while the context update is in progress, configs are still evaluated on the previous context.
+   *
+   */
+  get context(): ConfigDirectorContext | undefined;
+  /**
+   * Returns whether or not the client is ready after calling {@link initialize} or {@link updateContext}
+   *
+   * The definition of ready is that the connection to the server was successful, and config state
+   * was received.
+   */
+  get isReady(): boolean;
+  /**
+   * Returns whether or not the client is currently initializing. Upon client creation, it is `false`.
+   * It is `true` after calling `initialize` and becomes `false` again once initialization is completed.
+   */
+  get isInitializing(): boolean;
+  /**
+   * Evaluates a config and returns its value based on the current context and targeting rules
+   *
+   * @returns The evaluated config value, or the `defaultValue` if the config state was unavailable
+   * @param configKey The config key to evaluate
+   * @param defaultValue The default value to be returned if the config state is unavailable. For
+   * example, if the client cannot connect to the server due to network conditions, or if getValue
+   * is called before initialization is done.
+   */
+  getValue<T extends ConfigValueType>(configKey: string, defaultValue: T): T;
+  /**
+   * Watches for changes to a a config evaluation value. Whenever the config value changes, the
+   * provided callback function will be called with the new value. Changes can happen due to updates
+   * to the config in the ConfigDirector dashboard, or if the context is updated via {@link updateContext}.
+   *
+   * @returns An 'unwatch' function that can be called to remove the subscriber
+   *
+   * @param configKey The config key to watch
+   * @param defaultValue The default value to be referenced if the config state is unavailable
+   * @param callback The callback function to be called whenever the config value is updated
+   */
+  watch<T extends ConfigValueType>(configKey: string, defaultValue: T, callback: WatchHandler<T>): () => void;
+  /**
+   * Removes a particular subscriber to the given `configKey`, or all subscribers if no callback
+   * is provided.
+   *
+   * @param configKey The config key to remove subscribers from
+   * @param callback The subscriber to be removed. If not provided, all subscribers are removed for
+   * the given `configKey`.
+   */
+  unwatch<T extends ConfigValueType>(configKey: string, callback?: WatchHandler<T>): void;
+  /**
+   * Removes all subscribers from all config keys
+   */
+  unwatchAll(): void;
+  /**
+   * Pauses the network connection without clearing event handlers, watch handlers, or config
+   * state. Intended for mobile environments where the OS may kill background connections (e.g.
+   * when the app is backgrounded on iOS/Android).
+   *
+   * Call {@link resumeNetwork} to re-establish the connection.
+   */
+  pauseNetwork(): void;
+  /**
+   * Resumes a connection that was paused via {@link pauseNetwork}, using the last context that
+   * was provided to {@link initialize} or {@link updateContext}.
+   */
+  resumeNetwork(): Promise<void>;
+  /**
+   * Disposes of the client. All connections are closed, and all event and config key subscribers
+   * are removed.
+   *
+   * Intended to be called when your application shuts down
+   */
+  dispose(): void;
+}
+//#endregion
+export { ConfigDirectorClient as t };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@configdirector/nuxt-sdk",
+  "version": "0.1.0",
+  "description": "Nuxt SDK for ConfigDirector. ConfigDirector is a remote configuration and feature flag service.",
+  "license": "MIT",
+  "author": "ConfigDirector",
+  "keywords": [
+    "configdirector",
+    "configdirector vue",
+    "config",
+    "configuration",
+    "remote config",
+    "remote configuration",
+    "feature flag",
+    "feature toggle",
+    "feature switch"
+  ],
+  "homepage": "https://www.configdirector.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ConfigDirector/js-sdks"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/module.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "nuxt prepare && tsdown",
+    "prepack": "nuxt prepare && tsdown",
+    "release": "yarn lint && yarn ci:test && yarn build && npm publish --access public",
+    "lint": "eslint .",
+    "ci:test": "vitest run",
+    "test": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@jsonjoy.com/json-pointer": "^18.1.0",
+    "@nuxt/kit": "^4.4.2",
+    "consola": "^3.4.2",
+    "defu": "^6.1.7",
+    "rapidhash-js": "^3.0.0",
+    "semver": "^7.7.4"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.4",
+    "@nuxt/eslint-config": "^1.15.2",
+    "@nuxt/schema": "^4.4.2",
+    "@nuxt/test-utils": "^4.0.2",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.2.1",
+    "nuxt": "^4.4.2",
+    "playwright": "^1.52.0",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.21.7",
+    "tslib": "^2.8.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.10",
+    "vitest": "^4.1.4",
+    "vue-tsc": "^3.2.7"
+  }
+}