@configdirector/nuxt-sdk 0.1.1 → 0.5.0

package/README.md

@@ -1,150 +1,12 @@
 # ConfigDirector Nuxt SDK
 
-## Getting started
+This is the Nuxt SDK for [ConfigDirector](https://www.configdirector.com).
 
-### 1. Install
+## Documentation
 
-Install from NPM:
+Refer to the [official documentation for the Nuxt SDK](https://docs.configdirector.com/sdks/meta/nuxt).
 
-```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>
-```
-
-The `value` returned is a ShallowRef that will update whenever the config value is updated in the ConfigDirector dashboard, or if it evaluates to a different value due to targeting rules (for example, if the user context is updated). Keep in mind that it is a ShallowRef when accessing it in scripts:
-
-```ts
-<script setup lang="ts">
-const { value: myConfigValue } = useConfigDirectorValue<string>("my-config", "default value");
-
-const someOtherDerivedValue = computed(() => `Hello ${myConfigValue.value}`);
-</script>
-
-<template>
-  <div>my-config is : {{ someOtherDerivedValue }}</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>
-```
-
-Additionally, 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` 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.
+There is also [a quickstart guide for ConfigDirector and any of our SDKs](https://docs.configdirector.com/getting-started/quickstart).
 
 ## Getting Help
 

package/dist/module.json

@@ -4,5 +4,5 @@
   "compatibility": {
     "nuxt": ">=4.0.0"
   },
-  "version": "0.1.1"
+  "version": "0.5.0"
 }

package/dist/module.mjs

@@ -5,7 +5,7 @@ var module_default = defineNuxtModule({
 	meta: {
 		name: "@configdirector/nuxt-sdk",
 		configKey: "configdirector",
-		compatibility: { nuxt: ">=4.0.0" }
+		compatibility: { nuxt: ">=3.7.0" }
 	},
 	defaults: {},
 	setup(options, nuxt) {
@@ -33,33 +33,35 @@ var module_default = defineNuxtModule({
 			middleware: true,
 			handler: resolver.resolve("./runtime/nitro/middleware")
 		});
-		addServerImports({
+		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")
-		});
+		addImports([
+			{
+				name: "useConfigDirectorClient",
+				as: "useConfigDirectorClient",
+				from: resolver.resolve("./runtime/app/composables/useConfigDirectorClient")
+			},
+			{
+				name: "useConfigDirectorStatus",
+				as: "useConfigDirectorStatus",
+				from: resolver.resolve("./runtime/app/composables/useConfigDirectorStatus")
+			},
+			{
+				name: "useConfigDirectorContext",
+				as: "useConfigDirectorContext",
+				from: resolver.resolve("./runtime/app/composables/useConfigDirectorContext")
+			},
+			{
+				name: "useConfigDirectorValue",
+				as: "useConfigDirectorValue",
+				from: resolver.resolve("./runtime/app/composables/useConfigDirectorValue")
+			}
+		]);
 	}
 });
 //#endregion

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { t as ConfigDirectorContext } from "../../types-CQWNx-gI.mjs";
+import { t as ConfigDirectorContext } from "../../types-BWxsGnk2.mjs";
 import { Ref } from "vue";
 
 //#region src/runtime/app/composables/useConfigDirectorContext.d.ts

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

@@ -1,4 +1,4 @@
-import { t as ConfigDirectorContext } from "../../types-CQWNx-gI.mjs";
+import { t as ConfigDirectorContext } from "../../types-BWxsGnk2.mjs";
 import { Ref } from "vue";
 
 //#region src/runtime/app/composables/useConfigDirectorContext.d.ts

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

@@ -1,4 +1,4 @@
-import { n as ConfigValueType } from "../../types-CQWNx-gI.mjs";
+import { r as ConfigValueType } from "../../types-BWxsGnk2.mjs";
 import { t as ClientStatus } from "../../types-CkzBXJwA.mjs";
 import { DeepReadonly, Ref, ShallowRef } from "vue";
 

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

@@ -1,4 +1,4 @@
-import { n as ConfigValueType } from "../../types-CQWNx-gI.mjs";
+import { r as ConfigValueType } from "../../types-BWxsGnk2.mjs";
 import { t as ClientStatus } from "../../types-CkzBXJwA.mjs";
 import { DeepReadonly, Ref, ShallowRef } from "vue";
 

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

@@ -1,124 +1,6 @@
 import * as _$h3 from "h3";
+import { ConfigDirectorClient } from "@configdirector/server-sdk";
 
-//#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" {

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

@@ -1,124 +1,6 @@
 import * as _$h3 from "h3";
+import { ConfigDirectorClient } from "@configdirector/server-sdk";
 
-//#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" {

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

@@ -1,4 +1,4 @@
-import { t as ConfigDirectorClient } from "../types-D9MFb76Q.mjs";
+import { t as ConfigDirectorClient } from "../types-DGQ1B6mZ.mjs";
 import * as _$nitropack from "nitropack";
 
 //#region src/runtime/nitro/plugin.d.ts

package/dist/runtime/nitro/plugin.d.ts

@@ -1,4 +1,4 @@
-import { t as ConfigDirectorClient } from "../types-D9MFb76Q.mjs";
+import { t as ConfigDirectorClient } from "../types-DGQ1B6mZ.mjs";
 import * as _$nitropack from "nitropack";
 
 //#region src/runtime/nitro/plugin.d.ts