@configdirector/nuxt-sdk 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# ConfigDirector Nuxt SDK
+
+## Getting started
+
+### 1. Install
+
+Install from NPM:
+
+```bash
+npm install --save @configdirector/nuxt-sdk
+```
+
+### 2. Configure the Nuxt module
+
+The Nuxt SDK requires the client SDK key for evaluation in the browser, and the server SDK key for server side rendering (SSR) and for server routes.
+
+You can provide the keys in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  //...
+  modules: ["@configdirector/nuxt-sdk"],
+  runtimeConfig: {
+    public: {
+      configdirector: {
+        clientSdkKey: "YOUR-CLIENT-SDK-KEY",
+      },
+    },
+    configdirector: {
+      serverSdkKey: "YOUR-SERVER-SDK-KEY", // This is a secret, do not commit to your source repository
+    },
+  },
+});
+```
+
+Since the server SDK key is a secret value, the recommended approach is to provide it via an environment variable:
+
+```bash
+export NUXT_CONFIGDIRECTOR_SERVER_SDK_KEY=YOUR-SERVER-SDK-KEY
+```
+
+The client key can also be provided via an environment variable, which overrides the key provided in: `nuxt.config.ts`:
+
+```bash
+export NUXT_PUBLIC_CONFIGDIRECTOR_CLIENT_SDK_KEY=YOUR-CLIENT-SDK-KEY
+```
+
+### 3. Retrieve config values
+
+Retrieve a config value with the `useConfigDirectorValue` composable:
+
+```ts
+<script setup lang="ts">
+const { value } = useConfigDirectorValue<string>("my-config", "default value");
+</script>
+
+<template>
+  <div>my-config is : {{ value }}</div>
+</template>
+```
+
+You can also determine if the client is still initializing, so rather than transition from the default value to the evaluated value, you can show a loading state until the client is ready and config values are evaluated:
+
+```ts
+<script setup lang="ts">
+const { value, loading } = useConfigDirectorValue<string>("my-config", "default value");
+</script>
+
+<template>
+  <div v-if="loading">Loading...</div>
+  <div v-else>my-config is : {{ value }}</div>
+</template>
+```
+
+Alternatively, you can also use the `useConfigDirectorStatus` composable to retrieve just the status:
+
+```ts
+<script setup lang="ts">
+const { loading } = useConfigDirectorStatus();
+</script>
+
+<template>
+  <div v-if="loading">Loading...</div>
+  <div v-else><SomeComponentThatUsesConfigValues /></div>
+</template>
+```
+
+### 4. Updating the user context
+
+Update the user context with the `useConfigDirectorContext` composable:
+
+```ts
+<script setup lang="ts">
+const { context, updateContext } = useConfigDirectorContext();
+const { value } = useConfigDirectorValue<string>("my-config", "default value");
+
+const onUpdate = () => {
+  updateContext({
+    id: "54321",
+    name: "Another User",
+  });
+};
+</script>
+
+<template>
+  <div>Current context: {{ context }}</div>
+  <div>my-config is : {{ value }}</div>
+  <button type="button" @click="onUpdate">Update Context</button>
+</template>
+```
+
+### 5. Retrieving config values in a server handler
+
+On the server side, there is a Nitro composable to retrieve the ConfigDirector client:
+
+```ts
+export default defineEventHandler(async (_event) => {
+  const client = useConfigDirectorClient();
+  return client.getValue("my-config", "default value");
+});
+```
+
+`getValue` can also accepts an optional user context:
+
+```ts
+export default defineEventHandler(async (_event) => {
+  const client = useConfigDirectorClient();
+  return client.getValue("my-config", "default value", { id: "some-user-id", name: "Example User" });
+});
+```
+
+The server side evaluation is performed entirely by the SDK. Unlike the browser client which must retrieve new values when the user context is updated, the server evaluator can evaluate targeting rules locally (without additional network requests to ConfigDirector) for any user context.
+
+## Getting Help
+
+Reach out to us via https://www.configdirector.com/support

package/dist/module.d.mts

@@ -0,0 +1,85 @@
+import * as _$_nuxt_schema0 from "@nuxt/schema";
+import { LogLevel } from "consola";
+
+//#region src/module.d.ts
+interface ConfigDirectorRuntimeConfig {
+  /**
+   * Your ConfigDirector Server SDK key. You can obtain this key from the ConfigDirector
+   * dashboard under the project settings.
+   *
+   * This is a secret value and should not be committed to a source code repository. Alternatively,
+   * it can be provided at runtime via the NUXT_CONFIGDIRECTOR_SERVER_SDK_KEY environment variable.
+   */
+  serverSdkKey: string;
+  /**
+   * Log level for the server side of the ConfigDirector Nuxt SDK, using consola's numeric levels.
+   * 0 = error, 1 = warn, 2 = log, 3 = info, 4 = debug, 5 = trace.
+   * This value overrides the module's logLevel and the global Nuxt/consola log level.
+   */
+  logLevel?: LogLevel;
+  /**
+   * Override the ConfigDirector server API base URL. Only update this if you are using a proxy
+   * for ConfigDirector.
+   * Can be set via the NUXT_CONFIGDIRECTOR_BASE_URL environment variable.
+   */
+  baseUrl?: string;
+}
+interface ConfigDirectorPublicRuntimeConfig {
+  /**
+   * Your ConfigDirector Client SDK key. You can obtain this key from the ConfigDirector
+   * dashboard under the project settings.
+   *
+   * This value is not a secret. It can alternatively be provided at runtime via the
+   * NUXT_PUBLIC_CONFIGDIRECTOR_CLIENT_SDK_KEY environment variable.
+   */
+  clientSdkKey: string;
+  /**
+   * Your app's name. This value can be used in ConfigDirector targeting rules.
+   */
+  appName?: string;
+  /**
+   * Your app's version. This value can be used in ConfigDirector targeting rules.
+   *
+   * This can be a semver value or an arbitrary string (like a commit hash).
+   */
+  appVersion?: string;
+  /**
+   * Log level for the client/browser side of the ConfigDirector Nuxt SDK, using consola's numeric levels.
+   * 0 = error, 1 = warn, 2 = log, 3 = info, 4 = debug, 5 = trace.
+   * This value overrides the module's logLevel and the global Nuxt/consola log level.
+   */
+  logLevel?: LogLevel;
+  /**
+   * Override the ConfigDirector client API base URL. Primarily useful for testing.
+   * When omitted, the default ConfigDirector client endpoint is used.
+   * Can be set via the NUXT_PUBLIC_CONFIGDIRECTOR_BASE_URL environment variable.
+   */
+  baseUrl?: string;
+}
+declare module "nuxt/schema" {
+  interface RuntimeConfig {
+    configdirector: ConfigDirectorRuntimeConfig;
+  }
+  interface PublicRuntimeConfig {
+    configdirector: ConfigDirectorPublicRuntimeConfig;
+  }
+}
+declare module "@nuxt/schema" {
+  interface RuntimeConfig {
+    configdirector: ConfigDirectorRuntimeConfig;
+  }
+  interface PublicRuntimeConfig {
+    configdirector: ConfigDirectorPublicRuntimeConfig;
+  }
+}
+interface ModuleOptions {
+  /**
+   * Log level for the ConfigDirector SDK, using consola's numeric levels.
+   * 0 = error, 1 = warn, 2 = log, 3 = info, 4 = debug, 5 = trace.
+   * When omitted, the SDK inherits the global Nuxt/consola log level.
+   */
+  logLevel?: LogLevel;
+}
+declare const _default: _$_nuxt_schema0.NuxtModule<ModuleOptions, ModuleOptions, false>;
+//#endregion
+export { ModuleOptions, _default as default };

package/dist/module.json

@@ -0,0 +1,8 @@
+{
+  "name": "@configdirector/nuxt-sdk",
+  "configKey": "configdirector",
+  "compatibility": {
+    "nuxt": ">=4.0.0"
+  },
+  "version": "0.1.0"
+}

package/dist/module.mjs

@@ -0,0 +1,66 @@
+import { addImports, addPlugin, addServerHandler, addServerImports, addServerPlugin, createResolver, defineNuxtModule, useLogger } from "@nuxt/kit";
+import { defu } from "defu";
+//#region src/module.ts
+var module_default = defineNuxtModule({
+	meta: {
+		name: "@configdirector/nuxt-sdk",
+		configKey: "configdirector",
+		compatibility: { nuxt: ">=4.0.0" }
+	},
+	defaults: {},
+	setup(options, nuxt) {
+		const logger = useLogger("configdirector");
+		const resolver = createResolver(import.meta.url);
+		nuxt.options.runtimeConfig.configdirector = defu(nuxt.options.runtimeConfig.configdirector, options.logLevel !== void 0 ? {
+			serverSdkKey: "",
+			logLevel: options.logLevel,
+			baseUrl: ""
+		} : {
+			serverSdkKey: "",
+			baseUrl: ""
+		});
+		nuxt.options.runtimeConfig.public.configdirector = defu(nuxt.options.runtimeConfig.public.configdirector, options.logLevel !== void 0 ? {
+			clientSdkKey: "",
+			logLevel: options.logLevel,
+			baseUrl: ""
+		} : {
+			clientSdkKey: "",
+			baseUrl: ""
+		});
+		logger.debug("ConfigDirector Nuxt module setup complete");
+		addServerPlugin(resolver.resolve("./runtime/nitro/plugin"));
+		addServerHandler({
+			middleware: true,
+			handler: resolver.resolve("./runtime/nitro/middleware")
+		});
+		addServerImports({
+			name: "useConfigDirectorClient",
+			as: "useConfigDirectorClient",
+			from: resolver.resolve("./runtime/server/composables/useConfigDirectorClient")
+		});
+		addPlugin(resolver.resolve("./runtime/plugin.server"));
+		addPlugin(resolver.resolve("./runtime/plugin.client"));
+		addImports({
+			name: "useConfigDirectorClient",
+			as: "useConfigDirectorClient",
+			from: resolver.resolve("./runtime/app/composables/useConfigDirectorClient")
+		});
+		addImports({
+			name: "useConfigDirectorStatus",
+			as: "useConfigDirectorStatus",
+			from: resolver.resolve("./runtime/app/composables/useConfigDirectorStatus")
+		});
+		addImports({
+			name: "useConfigDirectorContext",
+			as: "useConfigDirectorContext",
+			from: resolver.resolve("./runtime/app/composables/useConfigDirectorContext")
+		});
+		addImports({
+			name: "useConfigDirectorValue",
+			as: "useConfigDirectorValue",
+			from: resolver.resolve("./runtime/app/composables/useConfigDirectorValue")
+		});
+	}
+});
+//#endregion
+export { module_default as default };

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

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

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

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

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

@@ -0,0 +1,8 @@
+import { useNuxtApp } from "#app";
+//#region src/runtime/app/composables/useConfigDirectorClient.ts
+const useConfigDirectorClient = () => {
+	const { $configDirectorClient } = useNuxtApp();
+	return { client: $configDirectorClient };
+};
+//#endregion
+export { useConfigDirectorClient };

package/dist/runtime/app/composables/useConfigDirectorContext.d.mts

@@ -0,0 +1,12 @@
+import { t as ConfigDirectorContext } from "../../types-CQWNx-gI.mjs";
+import { Ref } from "vue";
+
+//#region src/runtime/app/composables/useConfigDirectorContext.d.ts
+declare const useConfigDirectorContext: () => {
+  context: Readonly<Ref<ConfigDirectorContext | undefined>>;
+  updateContext: (context: ConfigDirectorContext, options?: {
+    timeoutMilliseconds: number;
+  }) => Promise<void>;
+};
+//#endregion
+export { useConfigDirectorContext };

package/dist/runtime/app/composables/useConfigDirectorContext.d.ts

@@ -0,0 +1,12 @@
+import { t as ConfigDirectorContext } from "../../types-CQWNx-gI.mjs";
+import { Ref } from "vue";
+
+//#region src/runtime/app/composables/useConfigDirectorContext.d.ts
+declare const useConfigDirectorContext: () => {
+  context: Readonly<Ref<ConfigDirectorContext | undefined>>;
+  updateContext: (context: ConfigDirectorContext, options?: {
+    timeoutMilliseconds: number;
+  }) => Promise<void>;
+};
+//#endregion
+export { useConfigDirectorContext };

package/dist/runtime/app/composables/useConfigDirectorContext.mjs

@@ -0,0 +1,30 @@
+import { useConfigDirectorClient } from "./useConfigDirectorClient.mjs";
+import { useState } from "#app";
+import { readonly, toRaw } from "vue";
+//#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
+export { useConfigDirectorContext };

package/dist/runtime/app/composables/useConfigDirectorStatus.d.mts

@@ -0,0 +1,10 @@
+import { t as ClientStatus } from "../../types-CkzBXJwA.mjs";
+import { Ref, ShallowRef } from "vue";
+
+//#region src/runtime/app/composables/useConfigDirectorStatus.d.ts
+declare const useConfigDirectorStatus: () => {
+  readyStatus: Readonly<ShallowRef<ClientStatus>>;
+  loading: Readonly<Ref<boolean>>;
+};
+//#endregion
+export { useConfigDirectorStatus };

package/dist/runtime/app/composables/useConfigDirectorStatus.d.ts

@@ -0,0 +1,10 @@
+import { t as ClientStatus } from "../../types-CkzBXJwA.mjs";
+import { Ref, ShallowRef } from "vue";
+
+//#region src/runtime/app/composables/useConfigDirectorStatus.d.ts
+declare const useConfigDirectorStatus: () => {
+  readyStatus: Readonly<ShallowRef<ClientStatus>>;
+  loading: Readonly<Ref<boolean>>;
+};
+//#endregion
+export { useConfigDirectorStatus };

package/dist/runtime/app/composables/useConfigDirectorStatus.mjs

@@ -0,0 +1,13 @@
+import { useNuxtApp } from "#app";
+import { computed } from "vue";
+//#region src/runtime/app/composables/useConfigDirectorStatus.ts
+const useConfigDirectorStatus = () => {
+	const { $configDirectorClientReadyStatus } = useNuxtApp();
+	const readyStatus = $configDirectorClientReadyStatus;
+	return {
+		readyStatus,
+		loading: computed(() => readyStatus.value === "loading")
+	};
+};
+//#endregion
+export { useConfigDirectorStatus };

package/dist/runtime/app/composables/useConfigDirectorValue.d.mts

@@ -0,0 +1,12 @@
+import { n as ConfigValueType } from "../../types-CQWNx-gI.mjs";
+import { t as ClientStatus } from "../../types-CkzBXJwA.mjs";
+import { Ref, ShallowRef } from "vue";
+
+//#region src/runtime/app/composables/useConfigDirectorValue.d.ts
+declare const useConfigDirectorValue: <T extends ConfigValueType>(configKey: string, defaultValue: T) => {
+  value: ShallowRef<T>;
+  readyStatus: Readonly<Ref<ClientStatus>>;
+  loading: Readonly<Ref<boolean>>;
+};
+//#endregion
+export { useConfigDirectorValue };

package/dist/runtime/app/composables/useConfigDirectorValue.d.ts

@@ -0,0 +1,12 @@
+import { n as ConfigValueType } from "../../types-CQWNx-gI.mjs";
+import { t as ClientStatus } from "../../types-CkzBXJwA.mjs";
+import { Ref, ShallowRef } from "vue";
+
+//#region src/runtime/app/composables/useConfigDirectorValue.d.ts
+declare const useConfigDirectorValue: <T extends ConfigValueType>(configKey: string, defaultValue: T) => {
+  value: ShallowRef<T>;
+  readyStatus: Readonly<Ref<ClientStatus>>;
+  loading: Readonly<Ref<boolean>>;
+};
+//#endregion
+export { useConfigDirectorValue };

package/dist/runtime/app/composables/useConfigDirectorValue.mjs

@@ -0,0 +1,19 @@
+import { useConfigDirectorClient } from "./useConfigDirectorClient.mjs";
+import { useConfigDirectorStatus } from "./useConfigDirectorStatus.mjs";
+import { onBeforeUnmount, shallowRef } from "vue";
+//#region src/runtime/app/composables/useConfigDirectorValue.ts
+const useConfigDirectorValue = (configKey, defaultValue) => {
+	const { client } = useConfigDirectorClient();
+	const { readyStatus, loading } = useConfigDirectorStatus();
+	const configValue = shallowRef(client.getValue(configKey, defaultValue));
+	const watcher = (newValue) => configValue.value = newValue;
+	client.watch(configKey, defaultValue, watcher);
+	onBeforeUnmount(() => client.unwatch(configKey, watcher));
+	return {
+		value: configValue,
+		readyStatus,
+		loading
+	};
+};
+//#endregion
+export { useConfigDirectorValue };

package/dist/runtime/nitro/middleware.d.mts

@@ -0,0 +1,130 @@
+import * as _$h3 from "h3";
+
+//#region ../js-server-sdk/dist/configdirector-server.d.cts
+//#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;
+  };
+};
+/**
+ * Metadata about your application. It is recommended you include these values when configuring
+ * a ConfigDirector client so that you can use them in targeting rules.
+ */
+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
+//#region ../shared/src/logger.d.ts
+//#endregion
+//#region src/runtime/nitro/middleware.d.ts
+declare const _default: _$h3.EventHandler<_$h3.EventHandlerRequest, void>;
+declare module "h3" {
+  interface H3EventContext {
+    configDirectorClient: ConfigDirectorClient;
+  }
+}
+//#endregion
+export { _default as default };