@approck/nuxt-unleash 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bluecoaster
+
+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

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+<!--
+Get your module up and running quickly.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Find and replace all on all files (CMD+SHIFT+F):
+- Name: My Module
+- Package name: my-module
+- Description: My new Nuxt module
+-->
+
+# Nuxt Unleash Module
+
+Feature flags from [Unleash](https://www.getunleash.io) — including [GitLab feature flags](https://docs.gitlab.com/operations/feature_flags/), which serve an Unleash-compatible API — for Nuxt 3 and 4, evaluated on the server and delivered with the page.
+
+## Features
+
+- Flags are evaluated on the server with the Node SDK ([unleash-client](https://www.npmjs.com/package/unleash-client)) for the context of each request, and handed to the browser in the payload: the first HTML already has them, nothing appears after hydration.
+- One client per server process keeps the flag definitions in memory; every evaluation gets its own context, so concurrent requests of different people never share state.
+- The browser reads the flags again, in one request, only when the context changes (login, logout, another account).
+- With [@sidebase/nuxt-auth](https://auth.sidebase.io) the flags are evaluated for the signed-in person, and with [@sentry/nuxt](https://docs.sentry.io/platforms/javascript/guides/nuxt/) failures are reported — nothing to write in the app.
+- `useFeatureFlag(name)` is synchronous.
+- Server routes can evaluate flags themselves through `#unleash`.
+
+## Quick Setup
+
+```bash
+npm install @approck/nuxt-unleash
+```
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@approck/nuxt-unleash'],
+  unleash: {
+    // GitLab: Deploy > Feature flags > Configure
+    url: 'https://gitlab.example.com/api/v4/feature_flags/unleash/42',
+    instanceId: 'glffct-…',
+    // The environment the app runs in: GitLab scopes flag strategies to environments by this name.
+    appName: 'production',
+  },
+})
+```
+
+The settings are server-only runtime config, so they can be set at deploy time instead:
+`NUXT_UNLEASH_URL`, `NUXT_UNLEASH_INSTANCE_ID`, `NUXT_UNLEASH_APP_NAME`.
+
+| Option | Default | |
+| --- | --- | --- |
+| `url` | — | Unleash client API URL (GitLab: API URL). |
+| `instanceId` | — | GitLab: Instance ID. Never sent to the browser. |
+| `appName` | — | GitLab: environment name. |
+| `refreshInterval` | `15` | Seconds between refreshes of the flag definitions. |
+| `readyTimeout` | `5` | Seconds after the server starts in which renders wait, together, for the first definitions. No render waits after that: without definitions the flags are off until they arrive. |
+| `customApiPath` | `'unleash'` | The browser reads flags from `POST /api/<customApiPath>/features`. |
+
+Without `url`, `instanceId` or `appName` the app still starts; every flag is off and `unleash:error` is called.
+
+## Usage
+
+With @sidebase/nuxt-auth installed the module evaluates flags for the session's `id` as `userId`. nuxt-auth reads the session on the server, so the first HTML has that person's flags; login, logout and another account read them again.
+
+Without nuxt-auth the app tells the module whom to evaluate for. Write the context in a plugin — the module's own plugin runs after the app's plugins — and again whenever the person changes:
+
+```ts
+// plugins/unleash-context.ts
+export default defineNuxtPlugin(() => {
+  const userId = useCookie<string | null>('user-id')
+  useUnleashContext().value = userId.value ? { userId: userId.value } : {}
+})
+```
+
+Read flags anywhere:
+
+```ts
+const canvasEnabled = useFeatureFlag('canvas') // ComputedRef<boolean>
+const flags = useFeatureFlags() // Ref<string[] | null>: names of the flags that are on
+```
+
+A read that failed leaves every flag off and calls `unleash:error`. With @sentry/nuxt installed the module sends it to Sentry itself; otherwise subscribe to the hook:
+
+```ts
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('unleash:error', error => console.error(error))
+})
+```
+
+In a server route:
+
+```ts
+import { useUnleash } from '#unleash'
+
+export default defineEventHandler(async () => {
+  const client = await useUnleash()
+  return client.isEnabled('my-flag', { userId: '42' })
+})
+```
+
+The context the browser posts is not verified: flags gate the interface, not access — whatever a flag hides must still be checked by the API.
+
+## Migrating from 0.1
+
+- Options: `clientKey` and `environment` are gone; set `instanceId` instead. `url` points at the Unleash client API (GitLab's API URL), not at an Unleash Proxy.
+- `useUnleash().isFeatureEnabled(flag, ctx)` is replaced by `useFeatureFlag(flag)`; the context is set once with `useUnleashContext()`.
+- On the server, `#unleash` exports `useUnleash()`, which resolves to the `unleash-client` instance: `isEnabled(name, context)`.
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
+  
+  ```bash
+  # Install dependencies
+  npm install
+  
+  # Generate type stubs
+  npm run dev:prepare
+  
+  # Develop with the playground
+  npm run dev
+  
+  # Build the playground
+  npm run dev:build
+  
+  # Run ESLint
+  npm run lint
+  
+  # Run Vitest
+  npm run test
+  npm run test:watch
+  
+  # Release new version
+  npm run release
+  ```
+
+</details>
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@approck/nuxt-unleash/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/@approck/nuxt-unleash
+[npm-downloads-src]: https://img.shields.io/npm/dm/@approck/nuxt-unleash.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/@approck/nuxt-unleash
+[license-src]: https://img.shields.io/npm/l/@approck/nuxt-unleash.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/@approck/nuxt-unleash
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.mts

@@ -0,0 +1,24 @@
+import { defineNuxtModule } from '@nuxt/kit';
+export { FeatureFlagsEvaluation, FeatureFlagsUnavailable, UnleashContext } from '../dist/runtime/types.js';
+
+interface ModuleOptions {
+    /** Unleash client API URL. GitLab: Deploy > Feature flags > Configure > API URL. */
+    url: string;
+    /** GitLab: Instance ID. Server-only: it authorizes reading the flags. */
+    instanceId: string;
+    /** GitLab: the environment the app runs in — flag strategies are scoped to environments by this name. */
+    appName: string;
+    /** Seconds between refreshes of the flag definitions on the server. */
+    refreshInterval: number;
+    /**
+     * Seconds after the server starts in which renders wait, together, for the first definitions. No render waits
+     * after that: without definitions the flags are off until they arrive.
+     */
+    readyTimeout: number;
+    /** Path segment of the endpoint the browser reads flags from: `/api/<customApiPath>/features`. */
+    customApiPath: string;
+}
+
+declare const _default: ReturnType<typeof defineNuxtModule<ModuleOptions>>;
+
+export { type ModuleOptions, _default as default };

package/dist/module.d.ts

@@ -0,0 +1,24 @@
+import { defineNuxtModule } from '@nuxt/kit';
+export { FeatureFlagsEvaluation, FeatureFlagsUnavailable, UnleashContext } from '../dist/runtime/types.js';
+
+interface ModuleOptions {
+    /** Unleash client API URL. GitLab: Deploy > Feature flags > Configure > API URL. */
+    url: string;
+    /** GitLab: Instance ID. Server-only: it authorizes reading the flags. */
+    instanceId: string;
+    /** GitLab: the environment the app runs in — flag strategies are scoped to environments by this name. */
+    appName: string;
+    /** Seconds between refreshes of the flag definitions on the server. */
+    refreshInterval: number;
+    /**
+     * Seconds after the server starts in which renders wait, together, for the first definitions. No render waits
+     * after that: without definitions the flags are off until they arrive.
+     */
+    readyTimeout: number;
+    /** Path segment of the endpoint the browser reads flags from: `/api/<customApiPath>/features`. */
+    customApiPath: string;
+}
+
+declare const _default: ReturnType<typeof defineNuxtModule<ModuleOptions>>;
+
+export { type ModuleOptions, _default as default };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@approck/nuxt-unleash",
+  "configKey": "unleash",
+  "version": "0.2.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,71 @@
+import { defineNuxtModule, createResolver, addServerPlugin, addServerHandler, hasNuxtModule, addPlugin, addImports, addTypeTemplate } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const moduleDefinition = defineNuxtModule({
+  meta: {
+    name: "@approck/nuxt-unleash",
+    configKey: "unleash"
+  },
+  defaults: {
+    url: "",
+    instanceId: "",
+    appName: "",
+    refreshInterval: 15,
+    readyTimeout: 5,
+    customApiPath: "unleash"
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    const { customApiPath, ...serverOptions } = options;
+    nuxt.options.runtimeConfig.unleash = defu(
+      nuxt.options.runtimeConfig.unleash,
+      serverOptions
+    );
+    const apiPath = `/api/${customApiPath}/features`;
+    nuxt.options.runtimeConfig.public.unleash = defu(
+      nuxt.options.runtimeConfig.public.unleash,
+      { apiPath }
+    );
+    addServerPlugin(resolve("./runtime/server/plugin"));
+    addServerHandler({
+      route: apiPath,
+      method: "post",
+      handler: resolve("./runtime/server/api/features.post")
+    });
+    nuxt.hook("modules:done", () => {
+      if (hasNuxtModule("@sidebase/nuxt-auth", nuxt)) {
+        addPlugin({ src: resolve("./runtime/plugins/auth-context"), mode: "all" }, { append: true });
+      }
+      if (hasNuxtModule("@sentry/nuxt/module", nuxt)) {
+        addPlugin({ src: resolve("./runtime/plugins/sentry"), mode: "all" }, { append: true });
+      }
+      addPlugin({ src: resolve("./runtime/plugin"), mode: "all" }, { append: true });
+    });
+    addImports(["useFeatureFlag", "useFeatureFlags", "useUnleashContext"].map((name) => ({
+      name,
+      from: resolve("./runtime/composables")
+    })));
+    nuxt.hook("nitro:config", (nitroConfig) => {
+      nitroConfig.alias = nitroConfig.alias || {};
+      nitroConfig.externals = defu(
+        typeof nitroConfig.externals === "object" ? nitroConfig.externals : {},
+        {
+          inline: [resolve("./runtime")]
+        }
+      );
+      nitroConfig.alias["#unleash"] = resolve("./runtime/server/services");
+    });
+    addTypeTemplate({
+      filename: "types/nuxt-unleash.d.ts",
+      getContents: () => [
+        "// AUTO-GENERATED BY @approck/nuxt-unleash",
+        "declare module '#unleash' {",
+        `  const { useUnleash }: typeof import('${resolve("./runtime/server/services")}')`,
+        "}",
+        ""
+      ].join("\n")
+    });
+  }
+});
+
+export { moduleDefinition as default };

package/dist/runtime/composables/index.d.ts

@@ -0,0 +1,14 @@
+import { type ComputedRef, type Ref } from 'vue';
+import type { UnleashContext } from '../types.js';
+/**
+ * The context flags are evaluated for. The application writes it — typically in a plugin, from its session — before
+ * the module's plugin runs (that one is enforced after the app's plugins), and again whenever the person changes.
+ */
+export declare function useUnleashContext(): Ref<UnleashContext>;
+/**
+ * Names of the flags that are on for the current context. Evaluated on the server and delivered with the page, so
+ * they are known from the first render; `null` only on a page rendered without SSR, until the browser reads them.
+ */
+export declare function useFeatureFlags(): Ref<string[] | null>;
+/** Whether a flag is on for the current context; off while the flags are not known. */
+export declare function useFeatureFlag(name: string): ComputedRef<boolean>;

package/dist/runtime/composables/index.js

@@ -0,0 +1,12 @@
+import { computed } from "vue";
+import { useState } from "#app";
+export function useUnleashContext() {
+  return useState("unleash-context", () => ({}));
+}
+export function useFeatureFlags() {
+  return useState("unleash-flags", () => null);
+}
+export function useFeatureFlag(name) {
+  const flags = useFeatureFlags();
+  return computed(() => flags.value?.includes(name) === true);
+}

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,15 @@
+import { FeatureFlagsUnavailable } from './types.js';
+declare module '#app' {
+    interface RuntimeNuxtHooks {
+        /** Flags could not be read and are all off for now — report it (e.g. to Sentry). */
+        'unleash:error': (error: FeatureFlagsUnavailable) => void | Promise<void>;
+    }
+}
+/**
+ * Server: evaluates every flag for the context the app wrote and hands the result to the browser in the payload.
+ * Browser: reads the flags again only when that context changes; a page rendered without SSR reads them once first.
+ * Flags of the previous context stay until the new ones arrive, so the interface does not blink on login or logout.
+ * A failed read turns every flag off and calls the `unleash:error` hook.
+ */
+declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,51 @@
+import { watch } from "vue";
+import { FetchError } from "ofetch";
+import { FeatureFlagsUnavailable } from "./types.js";
+import { useFeatureFlags, useUnleashContext } from "./composables/index.js";
+import { defineNuxtPlugin, useRequestEvent, useRuntimeConfig } from "#app";
+export default defineNuxtPlugin({
+  name: "@approck/nuxt-unleash",
+  // After the app's own plugins: they write the context and subscribe to `unleash:error` first.
+  enforce: "post",
+  async setup(nuxtApp) {
+    const flags = useFeatureFlags();
+    const context = useUnleashContext();
+    const fail = async (error) => {
+      flags.value = [];
+      await nuxtApp.callHook("unleash:error", error);
+    };
+    if (import.meta.server) {
+      const evaluate = useRequestEvent()?.context.unleashEvaluate;
+      if (!evaluate) throw new Error("@approck/nuxt-unleash: the server plugin did not attach unleashEvaluate");
+      const outcome = await evaluate({ ...context.value });
+      if ("unavailable" in outcome) {
+        await fail(new FeatureFlagsUnavailable(outcome.unavailable));
+        return;
+      }
+      flags.value = outcome.enabled;
+      return;
+    }
+    const { apiPath } = useRuntimeConfig().public.unleash;
+    let latestRead = 0;
+    const read = async () => {
+      const run = ++latestRead;
+      try {
+        const result = await $fetch(apiPath, {
+          method: "POST",
+          body: { context: context.value }
+        });
+        if (run === latestRead) flags.value = result.enabled;
+      } catch (error) {
+        if (!(error instanceof FetchError)) throw error;
+        if (run !== latestRead) return;
+        await fail(new FeatureFlagsUnavailable("the flags endpoint did not answer", { cause: error }));
+      }
+    };
+    if (!nuxtApp.payload.serverRendered) {
+      await read();
+    }
+    watch(() => JSON.stringify(context.value), () => {
+      void read();
+    });
+  }
+});

package/dist/runtime/plugins/auth-context.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Evaluates flags for the signed-in person of @sidebase/nuxt-auth: `userId` is the session's `id`. nuxt-auth reads
+ * the session on the server before the page renders, so the first HTML already has that person's flags; login,
+ * logout and another account change the context, and the module's plugin reads the flags again.
+ */
+declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugins/auth-context.js

@@ -0,0 +1,16 @@
+import { watch } from "vue";
+import { useUnleashContext } from "../composables/index.js";
+import { defineNuxtPlugin } from "#app";
+import { useAuth } from "#imports";
+export default defineNuxtPlugin({
+  name: "@approck/nuxt-unleash:auth-context",
+  // After nuxt-auth's own plugin has read the session; registered before the module's plugin, which reads the context.
+  enforce: "post",
+  setup() {
+    const { data } = useAuth();
+    const context = useUnleashContext();
+    watch(() => data.value?.id, (id) => {
+      context.value = id == null ? {} : { userId: String(id) };
+    }, { immediate: true });
+  }
+});

package/dist/runtime/plugins/sentry.d.ts

@@ -0,0 +1,3 @@
+/** Sends every `unleash:error` to the app's Sentry, on the server and in the browser. */
+declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugins/sentry.js

@@ -0,0 +1,10 @@
+import * as Sentry from "@sentry/nuxt";
+import { defineNuxtPlugin } from "#app";
+export default defineNuxtPlugin({
+  name: "@approck/nuxt-unleash:sentry",
+  setup(nuxtApp) {
+    nuxtApp.hook("unleash:error", (error) => {
+      Sentry.captureException(error);
+    });
+  }
+});

package/dist/runtime/server/api/features.post.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/api/features.post.js

@@ -0,0 +1,35 @@
+import { createError, defineEventHandler, readBody } from "#imports";
+const CONTEXT_FIELDS = ["userId", "sessionId", "remoteAddress"];
+function readContext(body) {
+  const source = body?.context;
+  if (typeof source !== "object" || source === null) {
+    throw createError({ statusCode: 400, statusMessage: "body.context must be an object" });
+  }
+  const context = {};
+  for (const field of CONTEXT_FIELDS) {
+    const value = source[field];
+    if (value === void 0) continue;
+    if (typeof value !== "string") {
+      throw createError({ statusCode: 400, statusMessage: `body.context.${field} must be a string` });
+    }
+    context[field] = value;
+  }
+  const properties = source.properties;
+  if (properties !== void 0) {
+    if (typeof properties !== "object" || properties === null || Object.values(properties).some((value) => typeof value !== "string")) {
+      throw createError({ statusCode: 400, statusMessage: "body.context.properties must map strings to strings" });
+    }
+    context.properties = properties;
+  }
+  return context;
+}
+export default defineEventHandler(async (event) => {
+  const context = readContext(await readBody(event));
+  const evaluate = event.context.unleashEvaluate;
+  if (!evaluate) throw new Error("@approck/nuxt-unleash: the server plugin did not attach unleashEvaluate");
+  const outcome = await evaluate(context);
+  if ("unavailable" in outcome) {
+    throw createError({ statusCode: 503, statusMessage: `Feature flags are unavailable: ${outcome.unavailable}` });
+  }
+  return outcome;
+});

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

@@ -0,0 +1,12 @@
+import { type FeatureFlagsOutcome, type UnleashContext } from '../types.js';
+declare module 'h3' {
+    interface H3EventContext {
+        /**
+         * Evaluates every flag for a context with this server's Unleash client. The Nuxt app is bundled apart from
+         * Nitro, so it reaches the one client through the request instead of importing its own copy.
+         */
+        unleashEvaluate?: (context: UnleashContext) => Promise<FeatureFlagsOutcome>;
+    }
+}
+declare const _default: any;
+export default _default;

package/dist/runtime/server/plugin.js

@@ -0,0 +1,22 @@
+import { FeatureFlagsUnavailable } from "../types.js";
+import { startUnleash, evaluateFlags } from "./unleash.js";
+import { defineNitroPlugin, useRuntimeConfig } from "#imports";
+export default defineNitroPlugin((nitroApp) => {
+  const config = useRuntimeConfig().unleash;
+  try {
+    startUnleash(config);
+  } catch (error) {
+    if (!(error instanceof FeatureFlagsUnavailable)) throw error;
+    console.error("[unleash]", error.message);
+  }
+  nitroApp.hooks.hook("request", (event) => {
+    event.context.unleashEvaluate = async (context) => {
+      try {
+        return await evaluateFlags(config, context);
+      } catch (error) {
+        if (!(error instanceof FeatureFlagsUnavailable)) throw error;
+        return { unavailable: error.reason };
+      }
+    };
+  });
+});

package/dist/runtime/server/services/index.d.ts

@@ -0,0 +1,2 @@
+/** The server's Unleash client once its definitions are loaded: `isEnabled(name, context)` for server routes. */
+export declare function useUnleash(): Promise<import("unleash-client").Unleash>;

package/dist/runtime/server/services/index.js

@@ -0,0 +1,5 @@
+import { useUnleashClient } from "../unleash.js";
+import { useRuntimeConfig } from "#imports";
+export function useUnleash() {
+  return useUnleashClient(useRuntimeConfig().unleash);
+}

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/runtime/server/unleash.d.ts

@@ -0,0 +1,23 @@
+import { Unleash } from 'unleash-client';
+import { type FeatureFlagsEvaluation, type UnleashContext } from '../types.js';
+export interface UnleashServerConfig {
+    url: string;
+    instanceId: string;
+    appName: string;
+    /** Seconds between refreshes of the flag definitions. */
+    refreshInterval: number;
+    /** Seconds an evaluation waits for the first definitions before it fails. */
+    readyTimeout: number;
+}
+/**
+ * The one Unleash client of this server process. It keeps the flag definitions in memory and evaluates every call
+ * against the context passed to that call, so concurrent requests of different people never share state.
+ *
+ * Definitions are in memory from the first fetch, or from the backup file of an earlier run when the server is
+ * unreachable at start — those are real last-known flags, not a guess.
+ */
+export declare function startUnleash(config: UnleashServerConfig): Unleash;
+/** The client once its definitions are in memory, for server routes that evaluate flags themselves. */
+export declare function useUnleashClient(config: UnleashServerConfig): Promise<Unleash>;
+/** Every flag defined for this `appName`, evaluated for one context. */
+export declare function evaluateFlags(config: UnleashServerConfig, context: UnleashContext): Promise<FeatureFlagsEvaluation>;

package/dist/runtime/server/unleash.js

@@ -0,0 +1,52 @@
+import { Unleash, UnleashEvents } from "unleash-client";
+import { FeatureFlagsUnavailable } from "../types.js";
+let client;
+let startup;
+let hasDefinitions = false;
+function requireSetting(config, key) {
+  const value = config[key];
+  if (!value) throw new FeatureFlagsUnavailable(`runtimeConfig.unleash.${key} is not set`);
+  return value;
+}
+export function startUnleash(config) {
+  if (client) return client;
+  client = new Unleash({
+    url: requireSetting(config, "url"),
+    instanceId: requireSetting(config, "instanceId"),
+    appName: requireSetting(config, "appName"),
+    refreshInterval: config.refreshInterval * 1e3,
+    // GitLab accepts client metrics and drops them (lib/api/unleash.rb: "not supported yet").
+    disableMetrics: true
+  });
+  const started = client;
+  if (started.isSynchronized()) hasDefinitions = true;
+  started.once(UnleashEvents.Ready, () => {
+    hasDefinitions = true;
+  });
+  startup = new Promise((resolve) => {
+    if (hasDefinitions) return resolve();
+    const timer = setTimeout(resolve, config.readyTimeout * 1e3);
+    timer.unref();
+    started.once(UnleashEvents.Ready, () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+  client.on(UnleashEvents.Error, (error) => console.error("[unleash]", error));
+  client.on(UnleashEvents.Warn, (message) => console.warn("[unleash]", message));
+  return client;
+}
+async function readyClient(config) {
+  const unleash = startUnleash(config);
+  await startup;
+  if (!hasDefinitions) throw new FeatureFlagsUnavailable("no flag definitions since the server started");
+  return unleash;
+}
+export function useUnleashClient(config) {
+  return readyClient(config);
+}
+export async function evaluateFlags(config, context) {
+  const unleash = await readyClient(config);
+  const enabled = unleash.getFeatureToggleDefinitions().map((definition) => definition.name).filter((name) => unleash.isEnabled(name, context));
+  return { enabled };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Unleash context of one evaluation. The application fills it (see `useUnleashContext`); the module adds nothing
+ * of its own. `appName` and `environment` are not part of it: GitLab picks the environment from the client's
+ * `appName`, which is fixed per deployment in the module options.
+ */
+export type UnleashContext = {
+    userId?: string;
+    sessionId?: string;
+    remoteAddress?: string;
+    properties?: Record<string, string>;
+};
+/** Names of the flags that are on for a context. */
+export interface FeatureFlagsEvaluation {
+    enabled: string[];
+}
+/**
+ * What the server hands the Nuxt app for one context. The app and Nitro are separate bundles with their own copy of
+ * every class, so a failure crosses as data — an `instanceof` check on a thrown error would never match.
+ */
+export type FeatureFlagsOutcome = FeatureFlagsEvaluation | {
+    unavailable: string;
+};
+/** Flag definitions were not available in time, or the browser could not reach the module's endpoint. */
+export declare class FeatureFlagsUnavailable extends Error {
+    readonly reason: string;
+    constructor(reason: string, options?: ErrorOptions);
+}

package/dist/runtime/types.js

@@ -0,0 +1,8 @@
+export class FeatureFlagsUnavailable extends Error {
+  reason;
+  constructor(reason, options) {
+    super(`Feature flags are unavailable: ${reason}`, options);
+    this.reason = reason;
+    this.name = "FeatureFlagsUnavailable";
+  }
+}

package/dist/types.d.mts

@@ -0,0 +1 @@
+export { type FeatureFlagsEvaluation, type FeatureFlagsUnavailable, type UnleashContext } from './module.js'

package/dist/types.d.ts

@@ -0,0 +1 @@
+export { type FeatureFlagsEvaluation, type FeatureFlagsUnavailable, type UnleashContext } from './module'

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@approck/nuxt-unleash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Unleash and GitLab feature flags for Nuxt, evaluated on the server and delivered with the page.",
+  "repository": "https://github.com/adalekin/nuxt-unleash",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/module.mjs",
+      "require": "./dist/module.cjs"
+    }
+  },
+  "main": "./dist/module.cjs",
+  "types": "./dist/types.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build prepare && nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && changelogen --release && git push --follow-tags",
+    "release-temp": "npm run prepack && npm publish --access=public",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.14.1592",
+    "defu": "^6.1.4",
+    "ofetch": "^1.4.1",
+    "unleash-client": "^6.12.1"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^1.6.1",
+    "@nuxt/eslint-config": "^0.6.2",
+    "@nuxt/module-builder": "^0.8.4",
+    "@nuxt/schema": "^3.14.1592",
+    "@nuxt/test-utils": "^3.14.4",
+    "@types/node": "latest",
+    "changelogen": "^0.5.7",
+    "eslint": "^9.15.0",
+    "nuxt": "^3.14.1592",
+    "typescript": "latest",
+    "vitest": "^2.1.6",
+    "vue-tsc": "^2.1.10"
+  }
 }