Add @flags-sdk/supaship adapter

Author: madhusudhand

apps/docs/components/custom/logos/supaship.tsx

@@ -0,0 +1,61 @@
+export function SupashipLogo(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 159.02095 32.065632"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <g transform="matrix(0.12524871,0,0,0.12524871,0,0)">
+        <rect
+          width="256"
+          height="256"
+          rx="128"
+          fill="currentColor"
+          x="0"
+          y="0"
+        />
+        <line
+          x1="66"
+          y1="118"
+          x2="118"
+          y2="66"
+          fill="none"
+          stroke="currentColor"
+          filter="invert(1)"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="24"
+        />
+        <line
+          x1="186"
+          y1="70"
+          x2="70"
+          y2="186"
+          fill="none"
+          stroke="currentColor"
+          filter="invert(1)"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="24"
+        />
+        <line
+          x1="190"
+          y1="138"
+          x2="138"
+          y2="190"
+          fill="none"
+          stroke="currentColor"
+          filter="invert(1)"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="24"
+        />
+      </g>
+      <path
+        d="m 53.960735,20.017893 q 0,2.892657 -2.027857,4.443353 -1.998031,1.550696 -5.308214,1.550696 -1.968171,0 -3.817107,-0.477153 -1.819078,-0.477118 -2.892657,-1.371782 l 0.536798,-4.443351 2.654097,0.268451 -0.0594,2.3857 q 0.984131,0.506957 1.78931,0.656067 0.834983,0.119326 1.550697,0.119326 1.729648,0 2.862833,-0.536798 1.163053,-0.566604 1.163053,-2.236589 0,-1.819077 -1.312145,-2.415502 -1.312138,-0.626248 -3.011943,-0.954308 -1.371782,-0.268471 -2.773388,-0.715713 -1.401585,-0.447296 -2.326035,-1.491052 -0.924486,-1.043721 -0.924486,-3.07159 0,-3.0417479 2.057672,-4.3538849 2.087479,-1.341961 4.652127,-1.341961 1.789255,0 3.459276,0.536781 1.699789,0.536797 2.654069,1.401603 l 0.178896,4.0854869 -2.654065,0.238722 -0.268458,-2.5050039 q -0.835,-0.477102 -1.669984,-0.656068 -0.834983,-0.178897 -1.61034,-0.178897 -1.401588,0 -2.326035,0.56662 -0.924487,0.5666029 -0.924487,1.8190599 0,1.461283 1.133224,1.998046 1.162989,0.506958 2.594417,0.834982 1.222687,0.268454 2.773385,0.715712 1.550739,0.447333 2.683925,1.61038 1.163042,1.133185 1.163042,3.518902 z m 17.803237,5.695847 h -5.278375 v -2.236623 q -1.312104,2.505004 -4.413516,2.505004 -1.908528,0 -3.310121,-1.133222 -1.371775,-1.16301 -1.371775,-3.668014 v -6.411579 h -1.998036 v -2.445323 h 5.188881 v 7.69391 q 0,1.908526 0.685894,2.713689 0.685877,0.775357 1.938381,0.775357 1.491051,0 2.355855,-1.043719 0.894617,-1.04374 0.924437,-2.475147 v -5.218767 h -2.385688 v -2.445323 h 5.57658 V 23.26838 h 2.087483 z m 16.40169,-7.037824 q 0,2.862851 -1.52089,5.09944 -1.49105,2.236586 -4.62232,2.236586 -2.89265,0 -4.20478,-2.087494 v 5.63622 h 2.6541 v 2.50496 h -7.843 v -2.50496 h 1.99804 V 14.769306 h -2.08751 v -2.445323 h 5.27837 v 2.654115 q 0.56661,-1.192868 1.6402,-2.057671 1.10337,-0.864862 2.9523,-0.864862 2.56458,0 4.14515,1.759488 1.61034,1.729612 1.61034,4.860863 z m -3.31019,0.327936 q 0,-2.14714 -0.98407,-3.250504 -0.98408,-1.133222 -2.505,-1.133222 -1.61035,0 -2.5348,1.222687 -0.92441,1.222636 -0.98414,2.862836 l -0.0312,1.043737 q 0,1.670005 0.95429,2.683921 0.98407,1.013897 2.50495,1.013897 1.69985,0 2.62429,-1.192813 0.95426,-1.192866 0.95426,-3.250539 z m 6.32213,-5.695864 q 1.49107,-0.715712 2.65409,-0.984076 1.16301,-0.268472 2.68388,-0.268472 2.23664,0 3.668048,1.133222 1.46127,1.133223 1.46127,3.399633 v 6.023871 q 0,1.192868 0.98406,1.192868 0.26848,0 0.68589,-0.119326 l 0.0311,1.759434 q -0.9841,0.56662 -2.14714,0.56662 -2.534818,0 -2.743568,-2.654117 v -0.0594 q -0.59642,1.043775 -1.69978,1.878757 -1.07359,0.834985 -2.68393,0.834985 -1.4016,0 -2.77339,-0.834985 -1.34194,-0.864803 -1.34194,-2.982122 0,-2.475182 1.9682,-3.250521 1.96822,-0.80518 4.26445,-0.80518 0.56661,0 1.16304,0.03114 0.59639,0.03114 1.10335,0.08963 v -0.745535 q 0,-1.192868 -0.41755,-2.147141 -0.41754,-0.954254 -2.08748,-0.954254 -0.62626,0 -1.19284,0.08964 -0.53677,0.08963 -1.04377,0.357649 l -0.53679,2.057674 -2.56459,-0.268454 z m 7.27637,7.097469 v -0.477156 q -0.50696,-0.05939 -1.04372,-0.119326 -0.53678,-0.05939 -1.10341,-0.05939 -1.19286,0 -2.14715,0.417562 -0.92443,0.417563 -0.92443,1.669985 0,1.819114 1.9384,1.819114 1.13318,0 2.14713,-0.805162 1.0139,-0.835037 1.13318,-2.445378 z m 17.922568,1.312136 q 0,2.087494 -1.72962,3.19086 -1.69984,1.103402 -4.35394,1.103402 -1.43142,0 -2.89265,-0.327919 -1.43141,-0.327936 -2.59442,-0.98413 l 0.47711,-3.459277 2.50501,0.238739 -0.0312,1.72961 q 0.56662,0.238722 1.19287,0.327919 0.65607,0.08963 1.163,0.08963 1.22268,0 2.11732,-0.417545 0.92443,-0.44735 0.92443,-1.312154 0,-0.834985 -0.835,-1.192815 -0.80523,-0.358098 -2.02792,-0.536798 -1.22263,-0.208558 -2.44533,-0.5368 -1.22268,-0.357647 -2.05768,-1.133222 -0.80516,-0.80516 -0.80516,-2.385679 0,-2.326053 1.75947,-3.190861 1.78928,-0.86484 3.75749,-0.86484 2.59442,0 4.89068,1.22267 l 0.32792,3.310185 -2.50499,0.298202 -0.26848,-1.998046 q -1.16303,-0.447277 -2.35584,-0.447277 -0.92451,0 -1.58053,0.387812 -0.62626,0.358101 -0.62626,1.163045 0,0.835004 0.80517,1.163047 0.80519,0.327934 1.99803,0.53676 1.19283,0.178898 2.3857,0.5368 1.19286,0.327918 1.99801,1.133225 0.80517,0.775337 0.80517,2.355856 z m 17.6542,3.996075 h -7.18693 V 23.26829 h 1.99803 v -5.248534 q 0,-1.908561 -0.7157,-2.683918 -0.7157,-0.805161 -1.9384,-0.805161 -1.46124,0 -2.32607,0.954254 -0.86482,0.954308 -0.92446,2.326089 v 5.45727 h 1.96822 v 2.445378 h -7.15711 V 23.26829 h 1.99803 V 7.6419461 h -1.99803 v -2.445325 h 5.18889 v 9.3340559 q 1.37179,-2.4752 4.4434,-2.4752 1.93835,0 3.28033,1.163044 1.37176,1.163046 1.37176,3.638191 v 6.411578 h 1.99804 z m 3.13121,-16.1631439 v -3.51892 h 3.25054 v 3.51892 z m 5.338,16.1631439 h -7.1571 V 23.26829 h 1.99801 v -8.469251 h -2.11729 v -2.475127 h 5.27839 V 23.26829 h 1.99799 z m 16.521,-7.037822 q 0,2.862833 -1.52093,5.09942 -1.49105,2.236589 -4.62227,2.236589 -2.89265,0 -4.2048,-2.087496 v 5.636218 h 2.65411 v 2.504968 h -7.843 v -2.504968 h 1.99805 V 14.769236 h -2.08749 v -2.445324 h 5.27833 v 2.654096 q 0.56662,-1.192867 1.64017,-2.057672 1.10339,-0.864859 2.95232,-0.864859 2.56463,0 4.14514,1.759486 1.61037,1.729611 1.61037,4.860883 z m -3.31017,0.327916 q 0,-2.147139 -0.98408,-3.250488 -0.98415,-1.133239 -2.505,-1.133239 -1.61036,0 -2.53478,1.222688 -0.92452,1.222638 -0.98416,2.862835 l -0.0312,1.043739 q 0,1.670021 0.95434,2.683919 0.98405,1.013898 2.50494,1.013898 1.69982,0 2.6243,-1.192813 0.95424,-1.192868 0.95424,-3.250539 z"
+        fill="currentColor"
+        style={{ strokeWidth: '1.17407' }}
+      />
+    </svg>
+  );
+}

apps/docs/components/custom/provider-list.tsx

@@ -10,6 +10,7 @@ import { OptimizelyLogo } from './logos/optimizely';
 import { PostHogLogo } from './logos/posthog';
 import { ReflagLogo } from './logos/reflag';
 import { StatsigLogo } from './logos/statsig';
+import { SupashipLogo } from './logos/supaship';
 
 type Provider = {
   key: string;
@@ -104,6 +105,15 @@ const providers: Provider[] = [
     badges: ['Adapter', 'Flags Explorer'],
     glowColor: '#5d5dff',
   },
+  {
+    key: 'supaship',
+    name: 'Supaship',
+    href: '/providers/supaship',
+    logo: SupashipLogo,
+    badges: ['Adapter'],
+    glowColor: '#e4f222',
+    skipInvert: true,
+  },
   {
     key: 'openfeature',
     name: 'OpenFeature',

apps/docs/content/docs/providers/meta.json

@@ -17,6 +17,7 @@
     "reflag",
     "posthog",
     "flagsmith",
+    "supaship",
     "---OpenFeature---",
     "...openfeature",
     "---Others---",

apps/docs/content/docs/providers/supaship.mdx

@@ -0,0 +1,116 @@
+---
+title: 'Supaship'
+---
+
+The [Supaship](https://supaship.com/) provider contains support for Supaship feature flags.
+
+The `@flags-sdk/supaship` package provides an adapter for evaluating Supaship flags with the Flags SDK.
+
+<LearnMore icon="arrow" href="/providers">
+  Learn more about Adapters
+</LearnMore>
+
+---
+
+## Setup
+
+The Supaship provider is available in the `@flags-sdk/supaship` module. Install it with
+
+```bash
+npm install @flags-sdk/supaship
+```
+
+Set required variables:
+
+```sh
+SUPASHIP_SDK_KEY=your-supaship-sdk-key
+SUPASHIP_ENVIRONMENT=production
+```
+
+---
+
+## Provider Instance
+
+Import the default adapter instance `supashipAdapter` from `@flags-sdk/supaship`:
+
+```ts
+import { supashipAdapter } from '@flags-sdk/supaship';
+```
+
+If you need custom client settings, create an adapter instance manually:
+
+```ts
+import { createSupashipAdapter } from '@flags-sdk/supaship';
+
+const customSupashipAdapter = createSupashipAdapter({
+  sdkKey: process.env.SUPASHIP_SDK_KEY,
+  environment: process.env.SUPASHIP_ENVIRONMENT,
+  context: { app: 'dashboard' },
+  networkConfig: {
+    requestTimeoutMs: 5000,
+  },
+});
+```
+
+---
+
+## Identify Users
+
+Supaship uses context properties for targeting. Use `identify` to return those properties per request.
+
+```ts
+import { dedupe, flag } from 'flags/next';
+import type { Identify } from 'flags';
+import { supashipAdapter, type FeatureContext } from '@flags-sdk/supaship';
+
+const identify = dedupe((async ({ headers, cookies }) => {
+  const user = await getUser(headers, cookies);
+
+  return {
+    userId: user.id,
+    email: user.email,
+    plan: user.plan,
+  } satisfies FeatureContext;
+}) satisfies Identify<FeatureContext>);
+
+export const newHeader = flag<boolean, FeatureContext>({
+  key: 'new-header',
+  defaultValue: false,
+  identify,
+  adapter: supashipAdapter.feature(),
+});
+```
+
+<LearnMore icon="arrow" href="/frameworks/next/dedupe">
+  Learn more about `dedupe`
+</LearnMore>
+
+<LearnMore icon="arrow" href="/principles/evaluation-context">
+  Learn more about `identify`
+</LearnMore>
+
+---
+
+## Methods
+
+### `feature`
+
+Use `feature()` to evaluate a Supaship feature value:
+
+```ts
+import { flag } from 'flags/next';
+import { supashipAdapter, type FeatureContext } from '@flags-sdk/supaship';
+
+export const promoBanner = flag<boolean, FeatureContext>({
+  key: 'promo-banner',
+  defaultValue: false,
+  adapter: supashipAdapter.feature(),
+});
+```
+
+---
+
+## Read More
+
+- [Adapter Source Code](https://github.com/vercel/flags/tree/main/packages/adapter-supaship)
+- [Supaship JavaScript SDK](https://www.npmjs.com/package/@supashiphq/javascript-sdk)

packages/adapter-supaship/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @flags-sdk/supaship
+
+## 0.1.0
+
+### Minor Changes
+
+- Add initial Supaship adapter package.

packages/adapter-supaship/README.md

@@ -0,0 +1,70 @@
+# Flags SDK - Supaship Adapter
+
+The Supaship adapter for the [Flags SDK](https://flags-sdk.dev/) supports server-side feature evaluation powered by [Supaship](https://supaship.com/).
+
+## Setup
+
+Install the adapter:
+
+```bash
+pnpm i @flags-sdk/supaship
+```
+
+## Provider Instance
+
+Import the default adapter instance `supashipAdapter` from `@flags-sdk/supaship`:
+
+```ts
+import { supashipAdapter } from "@flags-sdk/supaship";
+```
+
+The default adapter is configured from:
+
+```sh
+export SUPASHIP_SDK_KEY="your-supaship-sdk-key"
+export SUPASHIP_ENVIRONMENT="production"
+```
+
+## Example
+
+```ts
+import { dedupe, flag } from "flags/next";
+import { supashipAdapter, type FeatureContext } from "@flags-sdk/supaship";
+
+const identify = dedupe(async (): Promise<FeatureContext> => {
+  return {
+    userId: "user-123",
+    plan: "pro",
+  };
+});
+
+export const newHeader = flag<boolean, FeatureContext>({
+  key: "new-header",
+  defaultValue: false,
+  identify,
+  adapter: supashipAdapter.feature(),
+});
+```
+
+## Custom Adapter
+
+Use `createSupashipAdapter` when you need custom client configuration:
+
+```ts
+import { createSupashipAdapter } from "@flags-sdk/supaship";
+
+const customSupashipAdapter = createSupashipAdapter({
+  sdkKey: process.env.SUPASHIP_SDK_KEY!,
+  environment: "staging",
+  context: { app: "dashboard" },
+  networkConfig: {
+    requestTimeoutMs: 5000,
+  },
+});
+```
+
+## Notes
+
+- This adapter uses Supaship's JavaScript SDK (`@supashiphq/javascript-sdk`) under the hood.
+- Supaship supports feature values of type `boolean`, `null`, `object`, and `array`.
+- If Supaship returns `null` or does not return a value, the flag `defaultValue` is used.

packages/adapter-supaship/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@flags-sdk/supaship",
+  "version": "0.1.0",
+  "description": "Supaship adapter for the Flags SDK",
+  "keywords": [
+    "flags-sdk",
+    "supaship",
+    "vercel",
+    "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",
+    "check": "biome check",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@supashiphq/javascript-sdk": "1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "20.11.17",
+    "flags": "workspace:*",
+    "rimraf": "6.1.2",
+    "tsup": "8.5.1",
+    "typescript": "5.6.3",
+    "vite": "5.4.21",
+    "vitest": "1.6.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}