@flags-sdk/bucket adapter (#96)

* init
* [@flags-sdk/bucket] getProviderData (#113)
* [@flags-sdk/bucket] various improvements (#121)
* Update framer-motion to motion for CI

---------

Co-authored-by: Ron Cohen <cohen1@gmail.com>
Co-authored-by: Aaron Morris <aaron@vercel.com>

Author: 3 people

.changeset/wicked-camels-suffer.md

@@ -0,0 +1,5 @@
+---
+'@flags-sdk/bucket': minor
+---
+
+Introduce Bucket adapter

examples/shirt-shop/components/product-detail-page/add-to-cart-button.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { motion, AnimatePresence } from 'framer-motion';
+import { motion, AnimatePresence } from 'motion/react';
 
 function Spinner() {
   return (

examples/shirt-shop/components/shopping-cart/shopping-cart-item.tsx

@@ -2,7 +2,7 @@
 import { CartItem } from '@/components/utils/cart-types';
 import { ShoppingBagIcon } from '@heroicons/react/24/outline';
 import { colorToImage } from '@/components/utils/images';
-import { motion } from 'framer-motion';
+import { motion } from 'motion/react';
 import Image from 'next/image';
 import { ShoppingCartRemoveButton } from './shopping-cart-remove-button';
 import Link from 'next/link';

examples/shirt-shop/components/shopping-cart/shopping-cart-list.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { AnimatePresence } from 'framer-motion';
+import { AnimatePresence } from 'motion/react';
 
 export function ShoppingCartList({ children }: { children: React.ReactNode }) {
   return (

examples/shirt-shop/components/shopping-cart/shopping-cart-remove-button.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { removeFromCart } from '@/lib/actions';
-import { motion, AnimatePresence } from 'framer-motion';
+import { motion, AnimatePresence } from 'motion/react';
 import { useState } from 'react';
 import { CartItem } from '@/components/utils/cart-types';
 

examples/shirt-shop/package.json

@@ -22,8 +22,8 @@
     "@vercel/toolbar": "0.1.36",
     "clsx": "2.1.1",
     "flags": "workspace:*",
-    "framer-motion": "12.4.7",
     "js-xxhash": "4.0.0",
+    "motion": "12.12.1",
     "nanoid": "5.1.2",
     "next": "15.2.2-canary.4",
     "react": "^19.0.0",

packages/adapter-bucket/.eslintrc.cjs

@@ -0,0 +1,4 @@
+module.exports = {
+  root: true,
+  extends: [require.resolve('@pyra/eslint-config/components')],
+};

packages/adapter-bucket/README.md

@@ -0,0 +1,35 @@
+# Flags SDK - Bucket Provider
+
+The [Bucket provider](https://flags-sdk.dev/docs/api-reference/adapters/bucket) for the [Flags SDK](https://flags-sdk.dev/) contains support for Bucket's feature flags.
+
+## Setup
+
+The Bucket provider is available in the `@flags-sdk/bucket` module. You can install it with
+
+```bash
+pnpm i @flags-sdk/bucket
+```
+
+## Provider Instance
+
+You can import the default adapter instance `bucketAdapter` from `@flags-sdk/bucket`:
+
+```ts
+import { bucketAdapter } from '@flags-sdk/bucket';
+```
+
+## Example
+
+```ts
+import { flag } from 'flags/next';
+import { bucketAdapter } from '@flags-sdk/bucket';
+
+export const huddleFlag = flag<boolean>({
+  key: 'huddle',
+  adapter: bucketAdapter.featureIsEnabled(),
+});
+```
+
+## Documentation
+
+Please check out the [Bucket provider documentation](https://flags-sdk.dev/docs/api-reference/adapters/bucket) for more information.

packages/adapter-bucket/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@flags-sdk/bucket",
+  "version": "0.0.1",
+  "description": "Bucket.co provider for the Flags SDK",
+  "keywords": [
+    "flags-sdk",
+    "bucket.co",
+    "bucket",
+    "vercel",
+    "edge config",
+    "feature flags",
+    "flags"
+  ],
+  "homepage": "https://flags-sdk.dev",
+  "bugs": {
+    "url": "https://github.com/vercel/flags/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel/flags.git"
+  },
+  "license": "MIT",
+  "author": "",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.js",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "dist/*.d.ts",
+        "dist/*.d.cts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rimraf dist && tsup",
+    "dev": "tsup --watch --clean=false",
+    "eslint": "eslint-runner",
+    "eslint:fix": "eslint-runner --fix",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@bucketco/node-sdk": "1.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "20.11.17",
+    "eslint-config-custom": "workspace:*",
+    "flags": "workspace:*",
+    "msw": "2.6.4",
+    "rimraf": "6.0.1",
+    "tsconfig": "workspace:*",
+    "tsup": "8.0.1",
+    "typescript": "5.6.3",
+    "vite": "5.1.1",
+    "vitest": "1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/adapter-bucket/src/index.ts

@@ -0,0 +1,159 @@
+import type { Adapter, FlagDefinitionsType } from 'flags';
+import {
+  BucketClient,
+  ClientOptions,
+  Context,
+  ContextWithTracking,
+} from '@bucketco/node-sdk';
+import { ProviderData } from 'flags';
+
+export type { Context };
+
+type AdapterOptions = Pick<ContextWithTracking, 'enableTracking' | 'meta'>;
+
+type AdapterResponse = {
+  featureIsEnabled: (options?: AdapterOptions) => Adapter<boolean, Context>;
+  /** The Bucket client instance used by the adapter. */
+  bucketClient: () => Promise<BucketClient>;
+};
+
+let defaultBucketAdapter: ReturnType<typeof createBucketAdapter> | undefined;
+
+function assertEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`@flags-sdk/bucket: Missing ${name} environment variable`);
+  }
+  return value;
+}
+
+export function createBucketAdapter(
+  clientOptions: ClientOptions,
+): AdapterResponse {
+  let bucketClient: BucketClient;
+
+  async function initialize() {
+    if (!bucketClient) {
+      try {
+        bucketClient = new BucketClient(clientOptions);
+      } catch (err) {
+        // explicitly log out the error, otherwise it's swallowed
+        console.error('@flags-sdk/bucket: Error creating bucketClient', err);
+        throw err;
+      }
+    }
+
+    // this can be called multiple times. Same promise is returned.
+    return bucketClient.initialize();
+  }
+
+  function featureIsEnabled(
+    options?: AdapterOptions,
+  ): Adapter<boolean, Context> {
+    return {
+      async decide({ key, entities }): Promise<boolean> {
+        await initialize();
+
+        return bucketClient.getFeature({ ...options, ...entities }, key)
+          .isEnabled;
+      },
+    };
+  }
+
+  return {
+    featureIsEnabled,
+    bucketClient: async () => {
+      await initialize();
+      return bucketClient;
+    },
+  };
+}
+
+function getOrCreateDefaultAdapter() {
+  if (!defaultBucketAdapter) {
+    const secretKey = assertEnv('BUCKET_SECRET_KEY');
+
+    defaultBucketAdapter = createBucketAdapter({ secretKey });
+  }
+
+  return defaultBucketAdapter;
+}
+
+/**
+ * The default Bucket adapter.
+ *
+ * This is a convenience object that pre-initializes the Bucket SDK and provides
+ * the adapter function for usage with the Flags SDK.
+ *
+ * This is the recommended way to use the Bucket adapter.
+ *
+ * ```ts
+ * // flags.ts
+ * import { flag } from 'flags/next';
+ * import { bucketAdapter, type Context } from '@flags-sdk/bucket';
+ *
+ * const flag = flag<boolean, Context>({
+ *   key: 'my-flag',
+ *   defaultValue: false,
+ *   identify: () => ({ key: "user-123" }),
+ *   adapter: bucketAdapter.featureIsEnabled(),
+ * });
+ * ```
+ */
+export const bucketAdapter: AdapterResponse = {
+  featureIsEnabled: (...args) =>
+    getOrCreateDefaultAdapter().featureIsEnabled(...args),
+  bucketClient: async () => {
+    return getOrCreateDefaultAdapter().bucketClient();
+  },
+};
+
+/**
+ * Get the provider data for the Bucket adapter.
+ *
+ * This function is used the the [Flags API endpoint](https://vercel.com/docs/workflow-collaboration/feature-flags/implement-flags-in-toolbar#creating-the-flags-api-endpoint) to load and emit your Bucket data.
+ *
+ * ```ts
+ * // .well-known/vercel/flags/route.ts
+ * import { NextResponse, type NextRequest } from 'next/server';
+ * import { verifyAccess, type ApiData } from 'flags';
+ * import { bucketAdapter, getProviderData } from '@flags-sdk/bucket';
+ *
+ * export async function GET(request: NextRequest) {
+ *   const access = await verifyAccess(request.headers.get('Authorization'));
+ *   if (!access) return NextResponse.json(null, { status: 401 });
+ *
+ *   return NextResponse.json<ApiData>(
+ *     await getProviderData({ bucketClient: await bucketAdapter.bucketClient() }),
+ *   );
+ * }
+ * ```
+ */
+export async function getProviderData({
+  bucketClient,
+}: {
+  /**
+   * The BucketClient instance.
+   */
+  bucketClient?: BucketClient;
+} = {}): Promise<ProviderData> {
+  if (!bucketClient) {
+    bucketClient = await getOrCreateDefaultAdapter().bucketClient();
+  }
+
+  const features = await bucketClient.getFeatureDefinitions();
+
+  return {
+    definitions: features.reduce<FlagDefinitionsType>((acc, item) => {
+      acc[item.key] = {
+        options: [
+          { label: 'Disabled', value: false },
+          { label: 'Enabled', value: true },
+        ],
+        description: item.description ?? undefined,
+      };
+      return acc;
+    }, {}),
+    hints: [],
+  };
+}

packages/adapter-bucket/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "tsconfig/base.json",
+  "include": ["src"],
+  "compilerOptions": {
+    "lib": ["esnext"],
+    "resolveJsonModule": true,
+    "target": "ES2020"
+  }
+}

packages/adapter-bucket/tsup.config.js

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup';
+
+// eslint-disable-next-line import/no-default-export -- [@vercel/style-guide@5 migration]
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  splitting: true,
+  sourcemap: true,
+  minify: false,
+  clean: false,
+  skipNodeModulesBundle: true,
+  dts: true,
+  external: ['node_modules'],
+});

packages/adapter-bucket/vitest.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [],
+  test: { environment: 'node' },
+});