From 34856a368c2a1a592ba30850c7043c2d18b0bc38 Mon Sep 17 00:00:00 2001
From: Ron Cohen <ron@bucket.co>
Date: Fri, 20 Jun 2025 08:50:42 +0200
Subject: [PATCH 1/8] docs(vue-sdk): simplify getting started docs

---
 packages/vue-sdk/README.md | 37 ++-----------------------------------
 1 file changed, 2 insertions(+), 35 deletions(-)

diff --git a/packages/vue-sdk/README.md b/packages/vue-sdk/README.md
index 3c4f6eb8..3a3b1cbd 100644
--- a/packages/vue-sdk/README.md
+++ b/packages/vue-sdk/README.md
@@ -46,23 +46,6 @@ const huddle = useFeature("huddle");
 <template>
   <div v-if="huddle.isEnabled">
     <button @click="huddle.track()">Start huddle!</button>
-    <button
-      @click="
-        (e) =>
-          huddle.requestFeedback({
-            title:
-              huddle.config.payload?.question ??
-              'How do you like the Huddles feature?',
-            position: {
-              type: 'POPOVER',
-              anchor: e.currentTarget as HTMLElement,
-            },
-          })
-      "
-    >
-      Give feedback!
-    </button>
-  </div>
 </template>
 ```
 
@@ -128,24 +111,6 @@ The `<BucketProvider>` initializes the Bucket SDK, fetches features and starts l
 - `company`, `user` and `otherContext` make up the _context_ that is used to determine if a feature is enabled or not. `company` and `user` contexts are automatically transmitted to Bucket servers so the Bucket app can show you which companies have access to which features etc.
   > [!Note]
   > If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate feature targeting against,
-- `fallbackFeatures`: A list of strings which specify which features to consider enabled if the SDK is unable to fetch features. Can be provided in two formats:
-
-  ```ts
-  // Simple array of feature keys
-  fallbackFeatures={["feature1", "feature2"]}
-
-  // Or with configuration overrides
-  fallbackFeatures: {
-      "feature1": true,  // just enable the feature
-      "feature2": {      // enable with configuration
-        key: "variant-a",
-        payload: {
-          limit: 100,
-          mode: "test"
-        }
-      }
-  }
-  ```
 
 - `timeoutMs`: Timeout in milliseconds when fetching features from the server,
 - `staleWhileRevalidate`: If set to `true`, stale features will be returned while refetching features in the background,
@@ -217,6 +182,8 @@ const huddle = useFeature("huddle");
 </template>
 ```
 
+See the reference docs for details.
+
 ### `useTrack()`
 
 `useTrack()` lets you send custom events to Bucket. Use this whenever a user _uses_ a feature.

From 89baf1205123c3f7ea7d9b9ab26d3aeb8eb1b329 Mon Sep 17 00:00:00 2001
From: Ron Cohen <ron@bucket.co>
Date: Fri, 20 Jun 2025 08:53:02 +0200
Subject: [PATCH 2/8] wip on destructuring

---
 packages/vue-sdk/README.md                    | 29 +++++++++---
 .../plain/components/StartHuddleButton.vue    | 15 +++---
 packages/vue-sdk/src/hooks.ts                 | 46 ++++++++++++-------
 3 files changed, 58 insertions(+), 32 deletions(-)

diff --git a/packages/vue-sdk/README.md b/packages/vue-sdk/README.md
index 3c4f6eb8..d7df068a 100644
--- a/packages/vue-sdk/README.md
+++ b/packages/vue-sdk/README.md
@@ -66,6 +66,8 @@ const huddle = useFeature("huddle");
 </template>
 ```
 
+See [useFeature()](#usefeature) for a full example
+
 ## Setting `user` and `company`
 
 Bucket determines which features are active for a given `user`, `company`, or `otherContext`.
@@ -126,6 +128,7 @@ The `<BucketProvider>` initializes the Bucket SDK, fetches features and starts l
 
 - `publishableKey` is used to connect the provider to an _environment_ on Bucket. Find your `publishableKey` under [environment settings](https://app.bucket.co/envs/current/settings/app-environments) in Bucket,
 - `company`, `user` and `otherContext` make up the _context_ that is used to determine if a feature is enabled or not. `company` and `user` contexts are automatically transmitted to Bucket servers so the Bucket app can show you which companies have access to which features etc.
+
   > [!Note]
   > If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate feature targeting against,
 - `fallbackFeatures`: A list of strings which specify which features to consider enabled if the SDK is unable to fetch features. Can be provided in two formats:
@@ -183,26 +186,38 @@ If you want more control over loading screens, `useIsLoading()` returns a Ref<bo
 
 ### `useFeature()`
 
-Returns the state of a given feature for the current context. The composable provides type-safe access to feature flags and their configurations.
+Returns the state of a given feature for the current context. The composable provides access to feature flags and their configurations.
+
+Use feature returns an object with this approximate shape
+
+```ts
+{
+  isEnabled: boolean, // is the feature enabled
+  track: () => void, // send a track event when the feature is used
+  requestFeedback: (...) => void // open up a feedback dialog
+}
+```
+
+Example:
 
 ```vue
 <script setup lang="ts">
 import { useFeature } from "@bucketco/vue-sdk";
 
-const huddle = useFeature("huddle");
+const { isEnabled, track, requestFeedback, config } = useFeature("huddle");
 </script>
 
 <template>
-  <div v-if="huddle.isLoading">Loading...</div>
-  <div v-else-if="!huddle.isEnabled">Feature not available</div>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="!isEnabled">Feature not available</div>
   <div v-else>
-    <button @click="huddle.track()">Start huddle!</button>
+    <button @click="track()">Start huddle!</button>
     <button
       @click="
         (e) =>
-          huddle.requestFeedback({
+          requestFeedback({
             title:
-              huddle.config.payload?.question ??
+              config.payload?.question ??
               'How do you like the Huddles feature?',
             position: {
               type: 'POPOVER',
diff --git a/packages/vue-sdk/dev/plain/components/StartHuddleButton.vue b/packages/vue-sdk/dev/plain/components/StartHuddleButton.vue
index c1a0ce98..6e60e441 100644
--- a/packages/vue-sdk/dev/plain/components/StartHuddleButton.vue
+++ b/packages/vue-sdk/dev/plain/components/StartHuddleButton.vue
@@ -3,26 +3,25 @@ import { useFeature } from "../../../src";
 
 import Section from "./Section.vue";
 
-const huddle = useFeature("huddle");
+const { isLoading, isEnabled, config, requestFeedback, track } =
+  useFeature("huddle");
 </script>
 <template>
   <Section title="Huddle">
     <div style="display: flex; gap: 10px; flex-wrap: wrap">
-      <div>Huddle enabled: {{ huddle.isEnabled }}</div>
-      <div v-if="huddle.isLoading">Loading...</div>
+      <div>Huddle enabled: {{ isEnabled }}</div>
+      <div v-if="isLoading">Loading...</div>
       <div v-else style="display: flex; gap: 10px; flex-wrap: wrap">
         <div>
-          <button @click="huddle.track()">
-            {{
-              huddle.config.payload?.buttonTitle ?? "Start Huddle (track event)"
-            }}
+          <button @click="track()">
+            {{ config?.payload?.buttonTitle ?? "Start Huddle (track event)" }}
           </button>
         </div>
         <div>
           <button
             @click="
               (e) =>
-                huddle.requestFeedback({
+                requestFeedback({
                   title: 'Do you like huddles?',
                 })
             "
diff --git a/packages/vue-sdk/src/hooks.ts b/packages/vue-sdk/src/hooks.ts
index c6783bed..8b12f6c2 100644
--- a/packages/vue-sdk/src/hooks.ts
+++ b/packages/vue-sdk/src/hooks.ts
@@ -1,17 +1,24 @@
-import { inject, InjectionKey, onBeforeUnmount, ref } from "vue";
+import { inject, InjectionKey, onBeforeUnmount, ref, watch } from "vue";
 
-import { RequestFeedbackData, UnassignedFeedback } from "@bucketco/browser-sdk";
+import {
+  FeatureRemoteConfig,
+  RequestFeedbackData,
+  UnassignedFeedback,
+} from "@bucketco/browser-sdk";
 
 import {
   FeatureKey,
   ProviderContextType,
   RequestFeatureFeedbackOptions,
+  TypedFeatures,
 } from "./types";
 
 export const ProviderSymbol: InjectionKey<ProviderContextType> =
   Symbol("BucketProvider");
 
-export function useFeature<TKey extends FeatureKey>(key: TKey) {
+export function useFeature<TKey extends FeatureKey>(
+  key: TKey,
+): TypedFeatures[TKey] {
   const client = useClient();
   const ctx = injectSafe();
 
@@ -19,30 +26,35 @@ export function useFeature<TKey extends FeatureKey>(key: TKey) {
   const requestFeedback = (opts: RequestFeatureFeedbackOptions) =>
     client.value.requestFeedback({ ...opts, featureKey: key });
 
-  function getFeature() {
-    const f = client.value.getFeature(key);
-    return {
-      isEnabled: f.isEnabled,
-      config: f.config,
-      track,
-      requestFeedback,
-      key,
-      isLoading: ctx.isLoading,
-    };
-  }
+  const isEnabled = ref(false);
+  const config = ref<FeatureRemoteConfig | undefined>(undefined);
+  const isLoading = ref(false);
 
-  const feature = ref(getFeature());
+  updateFeature();
 
   function updateFeature() {
-    feature.value = getFeature();
+    const f = client.value.getFeature(key);
+
+    isEnabled.value = f.isEnabled;
+    config.value = f.config;
+    isLoading.value = ctx.isLoading.value;
   }
 
+  watch(ctx.isLoading, updateFeature);
+
   client.value.on("featuresUpdated", updateFeature);
   onBeforeUnmount(() => {
     client.value.off("featuresUpdated", updateFeature);
   });
 
-  return feature;
+  return {
+    isEnabled,
+    config: config as FeatureRemoteConfig,
+    track,
+    requestFeedback,
+    key,
+    isLoading,
+  };
 }
 
 /**

From 633495776482a26f306d9eabb000911c421daf3b Mon Sep 17 00:00:00 2001
From: Ron Cohen <ron@bucket.co>
Date: Fri, 20 Jun 2025 12:46:45 +0200
Subject: [PATCH 3/8] fix: useFeature() creates an object with Ref values
 instead of one big Ref

---
 packages/vue-sdk/README.md | 52 +++++++++-----------------------------
 1 file changed, 12 insertions(+), 40 deletions(-)

diff --git a/packages/vue-sdk/README.md b/packages/vue-sdk/README.md
index d7df068a..70de6b90 100644
--- a/packages/vue-sdk/README.md
+++ b/packages/vue-sdk/README.md
@@ -40,28 +40,12 @@ If using Nuxt, wrap `<BucketProvider>` in `<ClientOnly>`. `<BucketProvider>` onl
 <script setup lang="ts">
 import { useFeature } from "@bucketco/vue-sdk";
 
-const huddle = useFeature("huddle");
+const { isEnabled } = useFeature("huddle");
 </script>
 
 <template>
-  <div v-if="huddle.isEnabled">
-    <button @click="huddle.track()">Start huddle!</button>
-    <button
-      @click="
-        (e) =>
-          huddle.requestFeedback({
-            title:
-              huddle.config.payload?.question ??
-              'How do you like the Huddles feature?',
-            position: {
-              type: 'POPOVER',
-              anchor: e.currentTarget as HTMLElement,
-            },
-          })
-      "
-    >
-      Give feedback!
-    </button>
+  <div v-if="isEnabled">
+    <button>Start huddle!</button>
   </div>
 </template>
 ```
@@ -89,7 +73,9 @@ A number of special attributes exist:
   :publishableKey="publishableKey"
   :user="{ id: 'user_123', name: 'John Doe', email: 'john@acme.com' }"
   :company="{ id: 'acme_inc', plan: 'pro' }"
-></BucketProvider>
+>
+  <!-- your app -->
+</BucketProvider>
 ```
 
 To retrieve features along with their targeting information, use `useFeature(key: string)` hook (described in a section below).
@@ -131,24 +117,6 @@ The `<BucketProvider>` initializes the Bucket SDK, fetches features and starts l
 
   > [!Note]
   > If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate feature targeting against,
-- `fallbackFeatures`: A list of strings which specify which features to consider enabled if the SDK is unable to fetch features. Can be provided in two formats:
-
-  ```ts
-  // Simple array of feature keys
-  fallbackFeatures={["feature1", "feature2"]}
-
-  // Or with configuration overrides
-  fallbackFeatures: {
-      "feature1": true,  // just enable the feature
-      "feature2": {      // enable with configuration
-        key: "variant-a",
-        payload: {
-          limit: 100,
-          mode: "test"
-        }
-      }
-  }
-  ```
 
 - `timeoutMs`: Timeout in milliseconds when fetching features from the server,
 - `staleWhileRevalidate`: If set to `true`, stale features will be returned while refetching features in the background,
@@ -188,13 +156,15 @@ If you want more control over loading screens, `useIsLoading()` returns a Ref<bo
 
 Returns the state of a given feature for the current context. The composable provides access to feature flags and their configurations.
 
-Use feature returns an object with this approximate shape
+`useFeature()` returns an object with this shape:
 
 ```ts
 {
   isEnabled: boolean, // is the feature enabled
   track: () => void, // send a track event when the feature is used
   requestFeedback: (...) => void // open up a feedback dialog
+  config: {key: string, payload: any},  // remote configuration for this feature
+  isLoading: boolean // if you want to manage loading state at the feature level
 }
 ```
 
@@ -234,7 +204,9 @@ const { isEnabled, track, requestFeedback, config } = useFeature("huddle");
 
 ### `useTrack()`
 
-`useTrack()` lets you send custom events to Bucket. Use this whenever a user _uses_ a feature.
+`useTrack()` returns a function which lets you send custom events to Bucket. It takes a string argument with the event name and optionally an object with properties to attach the event.
+
+Using `track` returned from `useFeature()` calles this track function with the feature key as the event name.
 
 ```vue
 <script setup lang="ts">

From e6aa5b6051a93d7d064d6807721102c76b1fd58b Mon Sep 17 00:00:00 2001
From: Ron Cohen <ron@bucket.co>
Date: Mon, 23 Jun 2025 09:22:37 +0200
Subject: [PATCH 4/8] fix prettier

---
 packages/vue-sdk/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/vue-sdk/README.md b/packages/vue-sdk/README.md
index 3a3b1cbd..68e62bfd 100644
--- a/packages/vue-sdk/README.md
+++ b/packages/vue-sdk/README.md
@@ -109,6 +109,7 @@ The `<BucketProvider>` initializes the Bucket SDK, fetches features and starts l
 
 - `publishableKey` is used to connect the provider to an _environment_ on Bucket. Find your `publishableKey` under [environment settings](https://app.bucket.co/envs/current/settings/app-environments) in Bucket,
 - `company`, `user` and `otherContext` make up the _context_ that is used to determine if a feature is enabled or not. `company` and `user` contexts are automatically transmitted to Bucket servers so the Bucket app can show you which companies have access to which features etc.
+
   > [!Note]
   > If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate feature targeting against,
 

From 63567f58e873b15c595fac7c5cd4944b90e05748 Mon Sep 17 00:00:00 2001
From: Ron Cohen <ron@bucket.co>
Date: Mon, 23 Jun 2025 10:06:44 +0200
Subject: [PATCH 5/8] docs: use kebab-case convention

---
 packages/vue-sdk/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/vue-sdk/README.md b/packages/vue-sdk/README.md
index 68e62bfd..81de8126 100644
--- a/packages/vue-sdk/README.md
+++ b/packages/vue-sdk/README.md
@@ -24,7 +24,7 @@ import { BucketProvider } from "@bucketco/vue-sdk";
 </script>
 
 <BucketProvider
-  :publishableKey="publishableKey"
+  :publishable-key="publishableKey"
   :user="{ id: 'user_123', name: 'John Doe', email: 'john@acme.com' }"
   :company="{ id: 'acme_inc', plan: 'pro' }"
 >

From ffcda2d5c30be4532238b33ab7ebb674406268b2 Mon Sep 17 00:00:00 2001
From: Ron Cohen <ron@bucket.co>
Date: Mon, 23 Jun 2025 10:08:20 +0200
Subject: [PATCH 6/8] more kebab-case examples

---
 packages/vue-sdk/README.md         | 4 ++--
 packages/vue-sdk/dev/plain/App.vue | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/vue-sdk/README.md b/packages/vue-sdk/README.md
index 81de8126..e0e4fcb9 100644
--- a/packages/vue-sdk/README.md
+++ b/packages/vue-sdk/README.md
@@ -67,7 +67,7 @@ A number of special attributes exist:
 
 ```vue
 <BucketProvider
-  :publishableKey="publishableKey"
+  :publishable-key="publishableKey"
   :user="{ id: 'user_123', name: 'John Doe', email: 'john@acme.com' }"
   :company="{ id: 'acme_inc', plan: 'pro' }"
 ></BucketProvider>
@@ -133,7 +133,7 @@ BucketProvider lets you define a template to be shown while BucketProvider is in
 ```vue
 <template>
   <BucketProvider
-    :publishableKey="publishableKey"
+    :publishable-key="publishableKey"
     :user="user"
     :company="{ id: 'acme_inc', plan: 'pro' }"
   >
diff --git a/packages/vue-sdk/dev/plain/App.vue b/packages/vue-sdk/dev/plain/App.vue
index 5210efad..e535c509 100644
--- a/packages/vue-sdk/dev/plain/App.vue
+++ b/packages/vue-sdk/dev/plain/App.vue
@@ -20,7 +20,7 @@ const publishableKey = import.meta.env.VITE_PUBLISHABLE_KEY || "";
   </div>
   <BucketProvider
     v-else
-    :publishableKey="publishableKey"
+    :publishable-key="publishableKey"
     :user="user"
     :company="{ id: 'acme_inc', plan: 'pro' }"
   >

From dc28dec5d41961db63a6fa349e6cf451f138f4f8 Mon Sep 17 00:00:00 2001
From: Ron Cohen <ron@bucket.co>
Date: Mon, 23 Jun 2025 11:38:19 +0200
Subject: [PATCH 7/8] updating to support destructuring

---
 packages/vue-sdk/src/hooks.ts | 35 ++++++++++-------------------------
 packages/vue-sdk/src/types.ts |  2 +-
 2 files changed, 11 insertions(+), 26 deletions(-)

diff --git a/packages/vue-sdk/src/hooks.ts b/packages/vue-sdk/src/hooks.ts
index 8b12f6c2..b797b46b 100644
--- a/packages/vue-sdk/src/hooks.ts
+++ b/packages/vue-sdk/src/hooks.ts
@@ -1,24 +1,17 @@
-import { inject, InjectionKey, onBeforeUnmount, ref, watch } from "vue";
+import { computed, inject, InjectionKey, onBeforeUnmount, ref } from "vue";
 
-import {
-  FeatureRemoteConfig,
-  RequestFeedbackData,
-  UnassignedFeedback,
-} from "@bucketco/browser-sdk";
+import { RequestFeedbackData, UnassignedFeedback } from "@bucketco/browser-sdk";
 
 import {
-  FeatureKey,
+  Feature,
   ProviderContextType,
   RequestFeatureFeedbackOptions,
-  TypedFeatures,
 } from "./types";
 
 export const ProviderSymbol: InjectionKey<ProviderContextType> =
   Symbol("BucketProvider");
 
-export function useFeature<TKey extends FeatureKey>(
-  key: TKey,
-): TypedFeatures[TKey] {
+export function useFeature(key: string): Feature<any> {
   const client = useClient();
   const ctx = injectSafe();
 
@@ -26,34 +19,26 @@ export function useFeature<TKey extends FeatureKey>(
   const requestFeedback = (opts: RequestFeatureFeedbackOptions) =>
     client.value.requestFeedback({ ...opts, featureKey: key });
 
-  const isEnabled = ref(false);
-  const config = ref<FeatureRemoteConfig | undefined>(undefined);
-  const isLoading = ref(false);
+  const feature = ref(client.value.getFeature(key));
 
   updateFeature();
 
   function updateFeature() {
-    const f = client.value.getFeature(key);
-
-    isEnabled.value = f.isEnabled;
-    config.value = f.config;
-    isLoading.value = ctx.isLoading.value;
+    feature.value = client.value.getFeature(key);
   }
 
-  watch(ctx.isLoading, updateFeature);
-
   client.value.on("featuresUpdated", updateFeature);
   onBeforeUnmount(() => {
     client.value.off("featuresUpdated", updateFeature);
   });
 
   return {
-    isEnabled,
-    config: config as FeatureRemoteConfig,
+    key,
+    isEnabled: computed(() => feature.value.isEnabled),
+    config: computed(() => feature.value.config),
     track,
     requestFeedback,
-    key,
-    isLoading,
+    isLoading: computed(() => ctx.isLoading.value),
   };
 }
 
diff --git a/packages/vue-sdk/src/types.ts b/packages/vue-sdk/src/types.ts
index 7179674b..7d6adf2f 100644
--- a/packages/vue-sdk/src/types.ts
+++ b/packages/vue-sdk/src/types.ts
@@ -28,7 +28,7 @@ export interface Feature<
   key: string;
   isEnabled: Ref<boolean>;
   isLoading: Ref<boolean>;
-  config: ({ key: string } & TConfig) | EmptyFeatureRemoteConfig;
+  config: Ref<({ key: string } & TConfig) | EmptyFeatureRemoteConfig>;
   track(): Promise<Response | undefined> | undefined;
   requestFeedback: (opts: RequestFeatureFeedbackOptions) => void;
 }

From 4d6d1ebda1e6efce22151d15bac37784db4771a5 Mon Sep 17 00:00:00 2001
From: Ron Cohen <ron@bucket.co>
Date: Mon, 23 Jun 2025 12:23:51 +0200
Subject: [PATCH 8/8] fix docs

---
 packages/vue-sdk/src/index.ts | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/packages/vue-sdk/src/index.ts b/packages/vue-sdk/src/index.ts
index f587c0a6..887b28dc 100644
--- a/packages/vue-sdk/src/index.ts
+++ b/packages/vue-sdk/src/index.ts
@@ -9,7 +9,12 @@ import {
 } from "@bucketco/browser-sdk";
 
 import BucketProvider from "./BucketProvider.vue";
-import { BucketProps } from "./types";
+import {
+  BucketProps,
+  EmptyFeatureRemoteConfig,
+  Feature,
+  FeatureType,
+} from "./types";
 
 export {
   useClient,
@@ -29,6 +34,9 @@ export { BucketProvider };
 export type {
   CheckEvent,
   CompanyContext,
+  EmptyFeatureRemoteConfig,
+  Feature,
+  FeatureType,
   RawFeatures,
   TrackEvent,
   UserContext,