@buildrflags/vue 0.1.0

package/README.md

@@ -0,0 +1,190 @@
+# @buildrflags/vue
+
+Official Vue 3 SDK for [BuildrFlags](https://flags.buildrlab.com) — feature flags made simple.
+
+## Installation
+
+```bash
+npm install @buildrflags/vue
+# or
+pnpm add @buildrflags/vue
+# or
+yarn add @buildrflags/vue
+```
+
+## Quick Start
+
+### 1. Install the Plugin
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { BuildrFlagsPlugin } from '@buildrflags/vue';
+import App from './App.vue';
+
+const app = createApp(App);
+
+app.use(BuildrFlagsPlugin, {
+  apiKey: 'bf_production_xxx', // Your BuildrFlags API key
+});
+
+app.mount('#app');
+```
+
+### 2. Use Feature Flags in Components
+
+```vue
+<script setup lang="ts">
+import { useFlag } from '@buildrflags/vue';
+
+const { enabled, isLoading } = useFlag('new-checkout-flow');
+</script>
+
+<template>
+  <LoadingSpinner v-if="isLoading" />
+  <NewCheckout v-else-if="enabled" />
+  <OldCheckout v-else />
+</template>
+```
+
+## Composables
+
+### `useFlag(flagKey)`
+
+Get the evaluation result for a single flag.
+
+```vue
+<script setup lang="ts">
+import { useFlag } from '@buildrflags/vue';
+
+const { enabled, isLoading } = useFlag('dark-mode');
+</script>
+
+<template>
+  <DarkTheme v-if="enabled" />
+  <LightTheme v-else />
+</template>
+```
+
+### `useFlagValue(flagKey, defaultValue?)`
+
+Simple boolean access with optional default value.
+
+```vue
+<script setup lang="ts">
+import { useFlagValue } from '@buildrflags/vue';
+
+// Returns false while loading, true once flag is fetched (if enabled)
+const showBanner = useFlagValue('promo-banner', false);
+</script>
+
+<template>
+  <PromoBanner v-if="showBanner" />
+</template>
+```
+
+### `useFlags()`
+
+Get all flags with loading/error state and manual refresh.
+
+```vue
+<script setup lang="ts">
+import { useFlags } from '@buildrflags/vue';
+
+const { flags, isLoading, error, refresh } = useFlags();
+</script>
+
+<template>
+  <div v-if="error" class="error">{{ error }}</div>
+  <button @click="refresh">Refresh Flags</button>
+  <pre>{{ flags }}</pre>
+</template>
+```
+
+### `useFlagsEnabled(flagKeys, mode?)`
+
+Check multiple flags at once. Mode can be `'all'` (default) or `'any'`.
+
+```vue
+<script setup lang="ts">
+import { useFlagsEnabled } from '@buildrflags/vue';
+
+// All flags must be enabled
+const canAccessPremium = useFlagsEnabled(['premium-tier', 'new-dashboard'], 'all');
+
+// At least one flag must be enabled
+const showAnyPromo = useFlagsEnabled(['black-friday', 'cyber-monday'], 'any');
+</script>
+
+<template>
+  <PremiumDashboard v-if="canAccessPremium" />
+  <PromoSection v-if="showAnyPromo" />
+</template>
+```
+
+## Plugin Options
+
+```ts
+interface BuildrFlagsPluginOptions {
+  // Required: Your BuildrFlags API key
+  apiKey: string;
+
+  // Optional: Custom API base URL
+  // Default: 'https://api.flags.buildrlab.com'
+  baseUrl?: string;
+
+  // Optional: Auto-refresh interval in milliseconds
+  // Set to 0 to disable auto-refresh
+  // Default: 60000 (1 minute)
+  refreshInterval?: number;
+
+  // Optional: Pre-loaded flags for SSR/SSG
+  initialFlags?: Record<string, boolean>;
+}
+```
+
+## Server-Side Rendering (SSR)
+
+For SSR with Nuxt or similar, you can pre-load flags server-side:
+
+```ts
+// Server-side: fetch flags during SSR
+const response = await fetch('https://api.flags.buildrlab.com/api/evaluate/all', {
+  headers: { 'X-API-Key': 'bf_production_xxx' },
+});
+const { flags } = await response.json();
+
+// Convert to a simple map
+const initialFlags: Record<string, boolean> = {};
+for (const flag of flags) {
+  initialFlags[flag.flagKey] = flag.enabled;
+}
+
+// Pass to plugin
+app.use(BuildrFlagsPlugin, {
+  apiKey: 'bf_production_xxx',
+  initialFlags,
+});
+```
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions.
+
+```ts
+import type {
+  BuildrFlagsPluginOptions,
+  BuildrFlagsState,
+  UseFlagResult,
+  UseFlagsResult,
+} from '@buildrflags/vue';
+```
+
+## Requirements
+
+- Vue 3.3+
+- TypeScript 5.0+ (optional, but recommended)
+
+## License
+
+MIT © [BuildrLab](https://buildrlab.com)

package/dist/composables.d.ts

@@ -0,0 +1,89 @@
+import { type ComputedRef } from 'vue';
+import type { UseFlagResult, UseFlagsResult } from './types.js';
+/**
+ * Composable to get the evaluation result for a single flag.
+ *
+ * @param flagKey - The key of the flag to evaluate
+ * @returns Object with reactive `enabled` and `isLoading` refs
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFlag } from '@buildrflags/vue';
+ *
+ * const { enabled, isLoading } = useFlag('features.darkMode');
+ * </script>
+ *
+ * <template>
+ *   <Spinner v-if="isLoading" />
+ *   <DarkTheme v-else-if="enabled" />
+ *   <LightTheme v-else />
+ * </template>
+ * ```
+ */
+export declare function useFlag(flagKey: string): UseFlagResult;
+/**
+ * Composable to get all flags and loading/error state.
+ *
+ * @returns Object with reactive `flags`, `isLoading`, `error`, and `refresh` function
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFlags } from '@buildrflags/vue';
+ *
+ * const { flags, isLoading, error, refresh } = useFlags();
+ * </script>
+ *
+ * <template>
+ *   <div v-if="error">Error: {{ error }}</div>
+ *   <button @click="refresh">Refresh</button>
+ * </template>
+ * ```
+ */
+export declare function useFlags(): UseFlagsResult;
+/**
+ * Composable that returns just the boolean value for a flag as a computed ref.
+ * Returns the `defaultValue` (or `false`) while loading or if the flag is not found.
+ *
+ * @param flagKey - The key of the flag to evaluate
+ * @param defaultValue - Value to return while loading or when flag is missing (default: false)
+ * @returns Computed boolean ref
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFlagValue } from '@buildrflags/vue';
+ *
+ * const showBanner = useFlagValue('ui.showBanner', true);
+ * </script>
+ *
+ * <template>
+ *   <Banner v-if="showBanner" />
+ * </template>
+ * ```
+ */
+export declare function useFlagValue(flagKey: string, defaultValue?: boolean): ComputedRef<boolean>;
+/**
+ * Composable to check if multiple flags are enabled.
+ * Useful for checking feature combinations.
+ *
+ * @param flagKeys - Array of flag keys to check
+ * @param mode - 'all' (default) requires all flags enabled, 'any' requires at least one
+ * @returns Computed boolean ref
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFlagsEnabled } from '@buildrflags/vue';
+ *
+ * // All flags must be enabled
+ * const allEnabled = useFlagsEnabled(['feature.a', 'feature.b'], 'all');
+ *
+ * // At least one flag must be enabled
+ * const anyEnabled = useFlagsEnabled(['feature.a', 'feature.b'], 'any');
+ * </script>
+ * ```
+ */
+export declare function useFlagsEnabled(flagKeys: string[], mode?: 'all' | 'any'): ComputedRef<boolean>;
+//# sourceMappingURL=composables.d.ts.map

package/dist/composables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composables.d.ts","sourceRoot":"","sources":["../src/composables.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,WAAW,EAAY,MAAM,KAAK,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAqBlF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAUtD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAIzC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAOxF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,GAAE,KAAK,GAAG,KAAa,GAC1B,WAAW,CAAC,OAAO,CAAC,CAStB"}

package/dist/composables.js

@@ -0,0 +1,128 @@
+import { inject, computed } from 'vue';
+import { BUILDR_FLAGS_KEY } from './types.js';
+/**
+ * Injects the BuildrFlags state from the plugin.
+ *
+ * @throws Error if used outside of a component with BuildrFlagsPlugin installed
+ * @internal
+ */
+function useBuildrFlagsContext() {
+    const state = inject(BUILDR_FLAGS_KEY);
+    if (!state) {
+        throw new Error('BuildrFlags: useFlag/useFlags must be used within a component tree that has BuildrFlagsPlugin installed.');
+    }
+    return state;
+}
+/**
+ * Composable to get the evaluation result for a single flag.
+ *
+ * @param flagKey - The key of the flag to evaluate
+ * @returns Object with reactive `enabled` and `isLoading` refs
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFlag } from '@buildrflags/vue';
+ *
+ * const { enabled, isLoading } = useFlag('features.darkMode');
+ * </script>
+ *
+ * <template>
+ *   <Spinner v-if="isLoading" />
+ *   <DarkTheme v-else-if="enabled" />
+ *   <LightTheme v-else />
+ * </template>
+ * ```
+ */
+export function useFlag(flagKey) {
+    const { flags, isLoading } = useBuildrFlagsContext();
+    // Create a computed ref that tracks the specific flag
+    const enabled = computed(() => flags.value[flagKey] ?? false);
+    return {
+        enabled: enabled,
+        isLoading,
+    };
+}
+/**
+ * Composable to get all flags and loading/error state.
+ *
+ * @returns Object with reactive `flags`, `isLoading`, `error`, and `refresh` function
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFlags } from '@buildrflags/vue';
+ *
+ * const { flags, isLoading, error, refresh } = useFlags();
+ * </script>
+ *
+ * <template>
+ *   <div v-if="error">Error: {{ error }}</div>
+ *   <button @click="refresh">Refresh</button>
+ * </template>
+ * ```
+ */
+export function useFlags() {
+    const { flags, isLoading, error, refresh } = useBuildrFlagsContext();
+    return { flags, isLoading, error, refresh };
+}
+/**
+ * Composable that returns just the boolean value for a flag as a computed ref.
+ * Returns the `defaultValue` (or `false`) while loading or if the flag is not found.
+ *
+ * @param flagKey - The key of the flag to evaluate
+ * @param defaultValue - Value to return while loading or when flag is missing (default: false)
+ * @returns Computed boolean ref
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFlagValue } from '@buildrflags/vue';
+ *
+ * const showBanner = useFlagValue('ui.showBanner', true);
+ * </script>
+ *
+ * <template>
+ *   <Banner v-if="showBanner" />
+ * </template>
+ * ```
+ */
+export function useFlagValue(flagKey, defaultValue = false) {
+    const { flags, isLoading } = useBuildrFlagsContext();
+    return computed(() => {
+        if (isLoading.value)
+            return defaultValue;
+        return flags.value[flagKey] ?? defaultValue;
+    });
+}
+/**
+ * Composable to check if multiple flags are enabled.
+ * Useful for checking feature combinations.
+ *
+ * @param flagKeys - Array of flag keys to check
+ * @param mode - 'all' (default) requires all flags enabled, 'any' requires at least one
+ * @returns Computed boolean ref
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFlagsEnabled } from '@buildrflags/vue';
+ *
+ * // All flags must be enabled
+ * const allEnabled = useFlagsEnabled(['feature.a', 'feature.b'], 'all');
+ *
+ * // At least one flag must be enabled
+ * const anyEnabled = useFlagsEnabled(['feature.a', 'feature.b'], 'any');
+ * </script>
+ * ```
+ */
+export function useFlagsEnabled(flagKeys, mode = 'all') {
+    const { flags, isLoading } = useBuildrFlagsContext();
+    return computed(() => {
+        if (isLoading.value)
+            return false;
+        const checkFn = mode === 'all' ? 'every' : 'some';
+        return flagKeys[checkFn]((key) => flags.value[key] === true);
+    });
+}
+//# sourceMappingURL=composables.js.map

package/dist/composables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composables.js","sourceRoot":"","sources":["../src/composables.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAA8B,MAAM,KAAK,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,SAAS,qBAAqB;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAEvC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,qBAAqB,EAAE,CAAC;IAErD,sDAAsD;IACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC;IAE9D,OAAO;QACL,OAAO,EAAE,OAAkC;QAC3C,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,qBAAqB,EAAE,CAAC;IAErE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,YAAY,GAAG,KAAK;IAChE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,qBAAqB,EAAE,CAAC;IAErD,OAAO,QAAQ,CAAC,GAAG,EAAE;QACnB,IAAI,SAAS,CAAC,KAAK;YAAE,OAAO,YAAY,CAAC;QACzC,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,YAAY,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAkB,EAClB,OAAsB,KAAK;IAE3B,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,qBAAqB,EAAE,CAAC;IAErD,OAAO,QAAQ,CAAC,GAAG,EAAE;QACnB,IAAI,SAAS,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAElC,MAAM,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;QAClD,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * BuildrFlags Vue SDK
+ *
+ * Vue composables and plugin for feature flag evaluation.
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { createApp } from 'vue';
+ * import { BuildrFlagsPlugin } from '@buildrflags/vue';
+ * import App from './App.vue';
+ *
+ * const app = createApp(App);
+ *
+ * app.use(BuildrFlagsPlugin, {
+ *   apiKey: 'bf_production_xxx',
+ * });
+ *
+ * app.mount('#app');
+ * ```
+ *
+ * @example
+ * ```vue
+ * <!-- MyComponent.vue -->
+ * <script setup lang="ts">
+ * import { useFlag } from '@buildrflags/vue';
+ *
+ * const { enabled } = useFlag('my-feature');
+ * </script>
+ *
+ * <template>
+ *   <NewFeature v-if="enabled" />
+ *   <OldFeature v-else />
+ * </template>
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { BuildrFlagsPlugin, createBuildrFlagsState } from './plugin.js';
+export { useFlag, useFlags, useFlagValue, useFlagsEnabled } from './composables.js';
+export type { BuildrFlagsPluginOptions, BuildrFlagsState, UseFlagResult, UseFlagsResult, FlagResult, BulkEvaluateResponse, } from './types.js';
+export { BUILDR_FLAGS_KEY } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAGxE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGpF,YAAY,EACV,wBAAwB,EACxB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,UAAU,EACV,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,45 @@
+/**
+ * BuildrFlags Vue SDK
+ *
+ * Vue composables and plugin for feature flag evaluation.
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { createApp } from 'vue';
+ * import { BuildrFlagsPlugin } from '@buildrflags/vue';
+ * import App from './App.vue';
+ *
+ * const app = createApp(App);
+ *
+ * app.use(BuildrFlagsPlugin, {
+ *   apiKey: 'bf_production_xxx',
+ * });
+ *
+ * app.mount('#app');
+ * ```
+ *
+ * @example
+ * ```vue
+ * <!-- MyComponent.vue -->
+ * <script setup lang="ts">
+ * import { useFlag } from '@buildrflags/vue';
+ *
+ * const { enabled } = useFlag('my-feature');
+ * </script>
+ *
+ * <template>
+ *   <NewFeature v-if="enabled" />
+ *   <OldFeature v-else />
+ * </template>
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Plugin
+export { BuildrFlagsPlugin, createBuildrFlagsState } from './plugin.js';
+// Composables
+export { useFlag, useFlags, useFlagValue, useFlagsEnabled } from './composables.js';
+// Injection key (for advanced usage)
+export { BUILDR_FLAGS_KEY } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,SAAS;AACT,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAExE,cAAc;AACd,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAYpF,qCAAqC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,31 @@
+import { type Plugin } from 'vue';
+import type { BuildrFlagsPluginOptions, BuildrFlagsState } from './types.js';
+/**
+ * Creates the BuildrFlags state with automatic fetching and refresh.
+ *
+ * @internal
+ */
+export declare function createBuildrFlagsState(options: BuildrFlagsPluginOptions): BuildrFlagsState;
+/**
+ * Vue plugin for BuildrFlags.
+ *
+ * Install this plugin in your Vue app to provide feature flag state
+ * to all components via composables.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { BuildrFlagsPlugin } from '@buildrflags/vue';
+ * import App from './App.vue';
+ *
+ * const app = createApp(App);
+ *
+ * app.use(BuildrFlagsPlugin, {
+ *   apiKey: 'bf_production_xxx',
+ * });
+ *
+ * app.mount('#app');
+ * ```
+ */
+export declare const BuildrFlagsPlugin: Plugin<[BuildrFlagsPluginOptions]>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,KAAK,CAAC;AACjD,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAMpB;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,gBAAgB,CA2E1F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,CAAC,wBAAwB,CAAC,CAKhE,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,101 @@
+import { ref } from 'vue';
+import { BUILDR_FLAGS_KEY } from './types.js';
+const DEFAULT_BASE_URL = 'https://api.flags.buildrlab.com';
+const DEFAULT_REFRESH_INTERVAL = 60_000; // 1 minute
+/**
+ * Creates the BuildrFlags state with automatic fetching and refresh.
+ *
+ * @internal
+ */
+export function createBuildrFlagsState(options) {
+    const { apiKey, baseUrl, refreshInterval, initialFlags } = options;
+    const resolvedBaseUrl = (baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+    const resolvedRefreshInterval = refreshInterval ?? DEFAULT_REFRESH_INTERVAL;
+    const flags = ref(initialFlags ?? {});
+    const isLoading = ref(initialFlags === undefined);
+    const error = ref(null);
+    let intervalId;
+    let mounted = true;
+    const fetchFlags = async () => {
+        try {
+            const response = await fetch(`${resolvedBaseUrl}/api/evaluate/all`, {
+                method: 'GET',
+                headers: {
+                    'X-API-Key': apiKey,
+                },
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => 'Unknown error');
+                throw new Error(`API request failed: ${response.status} ${text}`);
+            }
+            const data = (await response.json());
+            if (!mounted)
+                return;
+            const flagMap = {};
+            for (const flag of data.flags) {
+                flagMap[flag.flagKey] = flag.enabled;
+            }
+            flags.value = flagMap;
+            error.value = null;
+            isLoading.value = false;
+        }
+        catch (err) {
+            if (!mounted)
+                return;
+            const message = err instanceof Error ? err.message : 'Failed to fetch flags';
+            error.value = message;
+            isLoading.value = false;
+        }
+    };
+    // Initial fetch
+    void fetchFlags();
+    // Set up auto-refresh
+    if (resolvedRefreshInterval > 0) {
+        intervalId = setInterval(() => {
+            void fetchFlags();
+        }, resolvedRefreshInterval);
+    }
+    // Cleanup function (called when plugin is uninstalled)
+    const cleanup = () => {
+        mounted = false;
+        if (intervalId !== undefined) {
+            clearInterval(intervalId);
+        }
+    };
+    // Store cleanup on the state for potential future use
+    flags.__cleanup = cleanup;
+    return {
+        flags,
+        isLoading,
+        error,
+        refresh: fetchFlags,
+    };
+}
+/**
+ * Vue plugin for BuildrFlags.
+ *
+ * Install this plugin in your Vue app to provide feature flag state
+ * to all components via composables.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { BuildrFlagsPlugin } from '@buildrflags/vue';
+ * import App from './App.vue';
+ *
+ * const app = createApp(App);
+ *
+ * app.use(BuildrFlagsPlugin, {
+ *   apiKey: 'bf_production_xxx',
+ * });
+ *
+ * app.mount('#app');
+ * ```
+ */
+export const BuildrFlagsPlugin = {
+    install(app, options) {
+        const state = createBuildrFlagsState(options);
+        app.provide(BUILDR_FLAGS_KEY, state);
+    },
+};
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAyB,MAAM,KAAK,CAAC;AAMjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,gBAAgB,GAAG,iCAAiC,CAAC;AAC3D,MAAM,wBAAwB,GAAG,MAAM,CAAC,CAAC,WAAW;AAEpD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAiC;IACtE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IAEnE,MAAM,eAAe,GAAG,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzE,MAAM,uBAAuB,GAAG,eAAe,IAAI,wBAAwB,CAAC;IAE5E,MAAM,KAAK,GAAG,GAAG,CAA0B,YAAY,IAAI,EAAE,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,GAAG,CAAgB,IAAI,CAAC,CAAC;IAEvC,IAAI,UAAsD,CAAC;IAC3D,IAAI,OAAO,GAAG,IAAI,CAAC;IAEnB,MAAM,UAAU,GAAG,KAAK,IAAmB,EAAE;QAC3C,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,eAAe,mBAAmB,EAAE;gBAClE,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE;oBACP,WAAW,EAAE,MAAM;iBACpB;aACF,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;gBAChE,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;YACpE,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyB,CAAC;YAE7D,IAAI,CAAC,OAAO;gBAAE,OAAO;YAErB,MAAM,OAAO,GAA4B,EAAE,CAAC;YAC5C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC9B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;YACvC,CAAC;YAED,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;YACtB,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;YACnB,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC;QAC1B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO;gBAAE,OAAO;YAErB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,CAAC;YAC7E,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;YACtB,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC;IAEF,gBAAgB;IAChB,KAAK,UAAU,EAAE,CAAC;IAElB,sBAAsB;IACtB,IAAI,uBAAuB,GAAG,CAAC,EAAE,CAAC;QAChC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,KAAK,UAAU,EAAE,CAAC;QACpB,CAAC,EAAE,uBAAuB,CAAC,CAAC;IAC9B,CAAC;IAED,uDAAuD;IACvD,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,OAAO,GAAG,KAAK,CAAC;QAChB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,aAAa,CAAC,UAAU,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CAAC;IAEF,sDAAsD;IACrD,KAA8C,CAAC,SAAS,GAAG,OAAO,CAAC;IAEpE,OAAO;QACL,KAAK;QACL,SAAS;QACT,KAAK;QACL,OAAO,EAAE,UAAU;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAuC;IACnE,OAAO,CAAC,GAAQ,EAAE,OAAiC;QACjD,MAAM,KAAK,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;QAC9C,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;CACF,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+import type { InjectionKey, Ref } from 'vue';
+/**
+ * A single flag result from the bulk evaluation API.
+ */
+export interface FlagResult {
+    flagKey: string;
+    enabled: boolean;
+    reason: string;
+    fetchedAt: string;
+}
+/**
+ * Response shape from GET /api/evaluate/all.
+ */
+export interface BulkEvaluateResponse {
+    flags: FlagResult[];
+}
+/**
+ * State held in the BuildrFlags Vue context.
+ */
+export interface BuildrFlagsState {
+    /** Map of flagKey → enabled boolean. */
+    flags: Ref<Record<string, boolean>>;
+    /** True until the first successful fetch completes. */
+    isLoading: Ref<boolean>;
+    /** Error message from the most recent fetch, or null. */
+    error: Ref<string | null>;
+    /** Manually refresh flags from the API. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Options for the BuildrFlags plugin.
+ */
+export interface BuildrFlagsPluginOptions {
+    /** Your BuildrFlags API key (starts with "bf_"). */
+    apiKey: string;
+    /** Base URL for the BuildrFlags API. @default "https://api.flags.buildrlab.com" */
+    baseUrl?: string;
+    /** Auto-refresh interval in milliseconds. Set to 0 to disable. @default 60000 */
+    refreshInterval?: number;
+    /** Pre-loaded flags for SSG/SSR (skips initial fetch when provided). */
+    initialFlags?: Record<string, boolean>;
+}
+/**
+ * Return type for the useFlag composable.
+ */
+export interface UseFlagResult {
+    /** Whether the flag is enabled (reactive). */
+    enabled: Ref<boolean>;
+    /** True until the first fetch completes (reactive). */
+    isLoading: Ref<boolean>;
+}
+/**
+ * Return type for the useFlags composable.
+ */
+export interface UseFlagsResult {
+    /** All flags as a key → boolean map (reactive). */
+    flags: Ref<Record<string, boolean>>;
+    /** True until the first fetch completes (reactive). */
+    isLoading: Ref<boolean>;
+    /** Error message from the most recent fetch, or null (reactive). */
+    error: Ref<string | null>;
+    /** Manually refresh flags from the API. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Injection key for the BuildrFlags context.
+ */
+export declare const BUILDR_FLAGS_KEY: InjectionKey<BuildrFlagsState>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpC,uDAAuD;IACvD,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACxB,yDAAyD;IACzD,KAAK,EAAE,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACtB,uDAAuD;IACvD,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpC,uDAAuD;IACvD,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACxB,oEAAoE;IACpE,KAAK,EAAE,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAAY,CAAC,gBAAgB,CAA0B,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Injection key for the BuildrFlags context.
+ */
+export const BUILDR_FLAGS_KEY = Symbol('buildr-flags');
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAuEA;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAmC,MAAM,CAAC,cAAc,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@buildrflags/vue",
+  "version": "0.1.0",
+  "description": "Vue composables and plugin for BuildrFlags feature flag evaluation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist node_modules"
+  },
+  "keywords": [
+    "feature-flags",
+    "buildrflags",
+    "vue",
+    "vue3",
+    "composables",
+    "feature-toggles"
+  ],
+  "author": "BuildrLab <hello@buildrlab.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buildrlab/buildrflags.git",
+    "directory": "sdks/vue"
+  },
+  "homepage": "https://flags.buildrlab.com",
+  "bugs": {
+    "url": "https://github.com/buildrlab/buildrflags/issues"
+  },
+  "peerDependencies": {
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@vitejs/plugin-vue": "^6.0.4",
+    "@vue/test-utils": "^2.4.0",
+    "eslint": "^10.0.0",
+    "happy-dom": "^20.6.1",
+    "typescript": "^5.6.0",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18",
+    "vue": "^3.5.0"
+  }
+}