✨ [FFL-2858] Feature Flags tab — catalog browsing (stacked PR 2 of 3) (#4916)

Author: kellyw1806

developer-extension/src/panel/components/tabs/flagsTab/flagCatalog.spec.ts

@@ -0,0 +1,202 @@
+import type { CatalogFlag, FlagCatalogRequest } from './flagCatalog'
+import { fetchFlagCatalog } from './flagCatalog'
+
+describe('flagCatalog', () => {
+  describe('fetchFlagCatalog', () => {
+    const baseRequest: FlagCatalogRequest = { page: 1, pageSize: 20, search: '', typeFilter: [], tagFilter: [] }
+
+    function mockResponse(body: unknown) {
+      return spyOn(globalThis, 'fetch').and.returnValue(Promise.resolve(new Response(JSON.stringify(body))))
+    }
+
+    it('requests one page server-side (active-only, offset from page) and returns the server total', async () => {
+      const sampleFlag: CatalogFlag = {
+        key: 'flag-a',
+        name: 'Flag A',
+        type: 'BOOLEAN',
+        variants: [{ name: 'on', value: true }],
+        tags: ['x'],
+      }
+      const sampleTotal = 42
+      const spy = mockResponse({
+        data: [
+          {
+            attributes: {
+              key: sampleFlag.key,
+              name: sampleFlag.name,
+              value_type: sampleFlag.type,
+              // The API returns variant values as strings; parseVariantValue turns them back.
+              variants: sampleFlag.variants.map(({ name, value }) => ({ name, value: String(value) })),
+              tags: sampleFlag.tags,
+            },
+          },
+        ],
+        meta: { page: { total: sampleTotal } },
+      })
+
+      const page = await fetchFlagCatalog('tok', 'datad0g.com', { ...baseRequest, page: 3, pageSize: 20 })
+
+      const [requestUrl, requestInit] = spy.calls.argsFor(0) as [string, RequestInit]
+      const url = new URL(requestUrl)
+      expect(url.pathname).toBe('/api/ui/ffe/feature-flags')
+      expect(url.searchParams.get('page[limit]')).toBe('20')
+      expect(url.searchParams.get('page[offset]')).toBe('40') // (3 - 1) * 20
+      expect(url.searchParams.get('is_archived')).toBe('false')
+      expect((requestInit.headers as Record<string, string>).Authorization).toBe('Bearer tok')
+      expect(page.total).toBe(sampleTotal)
+      expect(page.flags).toEqual([sampleFlag])
+    })
+
+    it('sends search, value_type (repeated), and tags (repeated) as server-side filters', async () => {
+      const spy = mockResponse({ data: [], meta: { page: { total: 0 } } })
+
+      await fetchFlagCatalog('tok', 'datad0g.com', {
+        page: 1,
+        pageSize: 20,
+        search: 'checkout',
+        typeFilter: ['BOOLEAN', 'STRING'],
+        tagFilter: ['team:x', 'beta'],
+      })
+
+      const [requestUrl] = spy.calls.argsFor(0) as [string, RequestInit]
+      const url = new URL(requestUrl)
+      expect(url.searchParams.get('search')).toBe('checkout')
+      expect(url.searchParams.getAll('value_type')).toEqual(['BOOLEAN', 'STRING'])
+      expect(url.searchParams.getAll('tags')).toEqual(['team:x', 'beta'])
+    })
+
+    it('omits the search param when the term is empty', async () => {
+      const spy = mockResponse({ data: [], meta: { page: { total: 0 } } })
+      await fetchFlagCatalog('tok', 'datad0g.com', baseRequest)
+      const [requestUrl] = spy.calls.argsFor(0) as [string, RequestInit]
+      expect(new URL(requestUrl).searchParams.has('search')).toBe(false)
+    })
+
+    it('parses variant values by declared type, falling back to the raw string on bad input', async () => {
+      mockResponse({
+        data: [
+          {
+            attributes: {
+              key: 'f',
+              value_type: 'JSON',
+              variants: [
+                { name: 'ok', value: '{"a":1}' },
+                { name: 'bad', value: 'not json' },
+              ],
+            },
+          },
+          {
+            attributes: {
+              key: 'n',
+              value_type: 'INTEGER',
+              variants: [
+                { name: 'five', value: '5' },
+                { name: 'nan', value: 'abc' },
+              ],
+            },
+          },
+        ],
+        meta: { page: { total: 2 } },
+      })
+
+      const { flags } = await fetchFlagCatalog('tok', 'datad0g.com', baseRequest)
+      expect(flags[0].variants[0].value).toEqual({ a: 1 })
+      expect(flags[0].variants[1].value).toBe('not json')
+      expect(flags[1].variants[0].value).toBe(5)
+      expect(flags[1].variants[1].value).toBe('abc')
+    })
+
+    it('keeps malformed or out-of-range variant values raw instead of coercing them', async () => {
+      mockResponse({
+        data: [
+          {
+            attributes: {
+              key: 'b',
+              value_type: 'BOOLEAN',
+              variants: [
+                { name: 't', value: 'true' },
+                { name: 'f', value: 'false' },
+                { name: 'weird', value: 'True' },
+              ],
+            },
+          },
+          {
+            attributes: {
+              key: 'i',
+              value_type: 'INTEGER',
+              variants: [
+                { name: 'partial', value: '5abc' },
+                { name: 'float', value: '5.5' },
+                { name: 'unsafe', value: '9007199254740993' },
+              ],
+            },
+          },
+          {
+            attributes: {
+              key: 'd',
+              value_type: 'NUMERIC',
+              variants: [
+                { name: 'ok', value: '5.5' },
+                { name: 'partial', value: '5abc' },
+                { name: 'empty', value: '' },
+              ],
+            },
+          },
+        ],
+        meta: { page: { total: 3 } },
+      })
+
+      const { flags } = await fetchFlagCatalog('tok', 'datad0g.com', baseRequest)
+      const [booleanFlag, integer, numeric] = flags
+      expect(booleanFlag.variants.map((variant) => variant.value)).toEqual([true, false, 'True'])
+      expect(integer.variants.map((variant) => variant.value)).toEqual(['5abc', '5.5', '9007199254740993'])
+      expect(numeric.variants.map((variant) => variant.value)).toEqual([5.5, '5abc', ''])
+    })
+
+    it('dedupes flags sharing a key within a page, keeping the first occurrence', async () => {
+      mockResponse({
+        data: [
+          { attributes: { key: 'dup', name: 'First', value_type: 'STRING', variants: [], tags: [] } },
+          { attributes: { key: 'dup', name: 'Second', value_type: 'STRING', variants: [], tags: [] } },
+        ],
+        meta: { page: { total: 2 } },
+      })
+
+      const { flags } = await fetchFlagCatalog('tok', 'datad0g.com', baseRequest)
+      expect(flags.length).toBe(1)
+      expect(flags[0].name).toBe('First')
+    })
+
+    it('falls back to the key for a missing name and defaults tags/variants', async () => {
+      mockResponse({ data: [{ attributes: { key: 'no-name', value_type: 'STRING' } }], meta: { page: { total: 1 } } })
+
+      const { flags } = await fetchFlagCatalog('tok', 'datad0g.com', baseRequest)
+      expect(flags[0].name).toBe('no-name')
+      expect(flags[0].tags).toEqual([])
+      expect(flags[0].variants).toEqual([])
+    })
+
+    it('tolerates a response that omits data/meta, falling total back to the page length', async () => {
+      mockResponse({ errors: ['x'] })
+      const page = await fetchFlagCatalog('tok', 'datad0g.com', baseRequest)
+      expect(page.flags).toEqual([])
+      expect(page.total).toBe(0)
+    })
+
+    it('falls back total to the number of returned flags when meta.page.total is missing', async () => {
+      mockResponse({
+        data: [{ attributes: { key: 'a', value_type: 'STRING' } }, { attributes: { key: 'b', value_type: 'STRING' } }],
+      })
+      expect((await fetchFlagCatalog('tok', 'datad0g.com', baseRequest)).total).toBe(2)
+    })
+
+    it('throws on a non-ok response', async () => {
+      spyOn(globalThis, 'fetch').and.returnValue(
+        Promise.resolve(new Response('err', { status: 500, statusText: 'Server Error' }))
+      )
+      await expectAsync(fetchFlagCatalog('tok', 'datad0g.com', baseRequest)).toBeRejectedWithError(
+        /Failed to fetch flag catalog/
+      )
+    })
+  })
+})

developer-extension/src/panel/components/tabs/flagsTab/flagCatalog.ts

@@ -0,0 +1,154 @@
+import type { FlagType } from './flagTypeConstants'
+import { getFlagsApiHost } from './oauth'
+
+export interface CatalogFlag {
+  key: string
+  name: string
+  type: FlagType
+  // Parsed value of each variant (any JSON value); see parseVariantValue.
+  variants: Array<{ name: string; value: unknown }>
+  tags: string[]
+}
+
+// Filters + pagination sent to the server so the FFE endpoint does the work — the extension never
+// loads the whole catalog. The endpoint applies all of these itself: `search` matches name/key/tags,
+// `tags` are AND-ed, `value_type` is OR-ed (see dd-source ffe-service). `page` is 1-based.
+export interface FlagCatalogRequest {
+  page: number
+  pageSize: number
+  search: string
+  typeFilter: string[]
+  tagFilter: string[]
+}
+
+// One page of results plus the server's total count (for pagination).
+export interface FlagCatalogPage {
+  flags: CatalogFlag[]
+  total: number
+}
+
+interface RawFeatureFlag {
+  attributes: {
+    key: string
+    name?: string
+    value_type: FlagType
+    variants?: Array<{ name: string; value: string }>
+    tags?: string[]
+  }
+}
+
+interface RawFeatureFlagsResponse {
+  data?: RawFeatureFlag[]
+  meta?: { page?: { total?: number } }
+}
+
+// Variant values come back from the API as strings regardless of the flag's declared type. Falls
+// back to the raw string on unparseable input so one malformed variant can't blow up the mapping
+// of the entire catalog.
+function parseVariantValue(type: FlagType, rawValue: string): unknown {
+  switch (type) {
+    case 'BOOLEAN':
+      // Only the exact strings count; anything else (e.g. "True", "falsex", "") is malformed and
+      // kept raw rather than silently collapsing to false.
+      if (rawValue === 'true') {
+        return true
+      }
+      if (rawValue === 'false') {
+        return false
+      }
+      return rawValue
+    case 'INTEGER': {
+      // parseInt would accept partial/oversized input ("5abc" -> 5, unsafe integers get rounded), so
+      // require the whole string to be an integer within the safe range; otherwise keep it raw.
+      const parsed = Number(rawValue)
+      return /^[+-]?\d+$/.test(rawValue) && Number.isSafeInteger(parsed) ? parsed : rawValue
+    }
+    case 'NUMERIC': {
+      // parseFloat accepts a numeric prefix ("5abc" -> 5) and Number("") is 0, so require a
+      // non-empty string that parses fully to a finite number; otherwise keep it raw.
+      const parsed = Number(rawValue)
+      return rawValue.trim() !== '' && Number.isFinite(parsed) ? parsed : rawValue
+    }
+    case 'JSON':
+      try {
+        return JSON.parse(rawValue) as unknown
+      } catch {
+        return rawValue
+      }
+    case 'STRING':
+      return rawValue
+    default:
+      // The server returned a value_type outside the known union (which is a compile-time
+      // assumption, not a runtime guarantee) — keep the raw string rather than returning undefined,
+      // consistent with never letting one odd variant blow up the mapping.
+      return rawValue
+  }
+}
+
+/**
+ * Fetches ONE page of the flag catalog via the FFE UI endpoint (GET /api/ui/ffe/feature-flags),
+ * letting the server apply the filters + pagination. Returns the page's flags plus the server's
+ * total match count (`meta.page.total`) so the caller can render pagination. OAuth is the only
+ * supported auth path (see oauth.ts).
+ */
+export async function fetchFlagCatalog(
+  token: string,
+  site: string,
+  request: FlagCatalogRequest
+): Promise<FlagCatalogPage> {
+  const url = new URL(`https://${getFlagsApiHost(site)}/api/ui/ffe/feature-flags`)
+  url.searchParams.set('page[limit]', String(request.pageSize))
+  url.searchParams.set('page[offset]', String((request.page - 1) * request.pageSize))
+  // Active flags only: with archived included, an archived and an active flag can share a key and
+  // land on the same page, which would render as duplicate rows and collide React keys.
+  url.searchParams.set('is_archived', 'false')
+  if (request.search) {
+    url.searchParams.set('search', request.search)
+  }
+  for (const type of request.typeFilter) {
+    url.searchParams.append('value_type', type)
+  }
+  for (const tag of request.tagFilter) {
+    url.searchParams.append('tags', tag)
+  }
+
+  const response = await fetch(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  })
+  if (!response.ok) {
+    throw new Error(`Failed to fetch flag catalog: ${response.status} ${response.statusText}`)
+  }
+
+  const body = (await response.json()) as RawFeatureFlagsResponse
+  // Tolerate a response that omits/mistypes `data` rather than throwing on `.map`.
+  const resources = Array.isArray(body?.data) ? body.data : []
+  return {
+    flags: mapResources(resources),
+    // Fall back to the page length when the server omits the total (e.g. a partial/legacy response).
+    total: body?.meta?.page?.total ?? resources.length,
+  }
+}
+
+function mapResources(resources: RawFeatureFlag[]): CatalogFlag[] {
+  // Dedupe by key as a cheap safety net against a flag appearing twice on a page (see is_archived
+  // note above); collisions would otherwise break React keys (`key={flag.key}`). Keep the first.
+  const byKey = new Map<string, CatalogFlag>()
+  for (const { attributes } of resources) {
+    if (byKey.has(attributes.key)) {
+      continue
+    }
+    byKey.set(attributes.key, {
+      key: attributes.key,
+      name: attributes.name || attributes.key,
+      type: attributes.value_type,
+      variants: (attributes.variants ?? []).map((variant) => ({
+        name: variant.name,
+        value: parseVariantValue(attributes.value_type, variant.value),
+      })),
+      tags: attributes.tags ?? [],
+    })
+  }
+  return Array.from(byKey.values())
+}